<html><head>
      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   <title>13.&nbsp;Object Relational Mapping (ORM) Data Access</title><link rel="stylesheet" href="css/stylesheet.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.74.0"><link rel="home" href="index.html" title="Reference Documentation"><link rel="up" href="spring-data-tier.html" title="Part&nbsp;IV.&nbsp;Data Access"><link rel="prev" href="jdbc.html" title="12.&nbsp;Data access with JDBC"><link rel="next" href="oxm.html" title="14.&nbsp;Marshalling XML using O/X Mappers"><!--Begin Google Analytics code--><script type="text/javascript">
			var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
			document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
		</script><script type="text/javascript">
			var pageTracker = _gat._getTracker("UA-2728886-3");
			pageTracker._setDomainName("none");
			pageTracker._setAllowLinker(true);
			pageTracker._trackPageview();
		</script><!--End Google Analytics code--></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">13.&nbsp;Object Relational Mapping (ORM) Data Access</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="jdbc.html">Prev</a>&nbsp;</td><th width="60%" align="center">Part&nbsp;IV.&nbsp;Data Access</th><td width="20%" align="right">&nbsp;<a accesskey="n" href="oxm.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="orm"></a>13.&nbsp;Object Relational Mapping (ORM) Data Access</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="orm-introduction"></a>13.1&nbsp;Introduction to ORM with Spring</h2></div></div></div><p>The Spring Framework supports integration
    with Hibernate, Java Persistence API (JPA), Java Data Objects (JDO) and
    iBATIS SQL Maps for resource management, data access object (DAO)
    implementations, and transaction strategies. For example, for Hibernate
    there is first-class support with several convenient IoC features that
    address many typical Hibernate integration issues. You can configure
    all of the supported features for O/R (object relational) mapping tools through
    Dependency Injection. They can participate in Spring's resource
    and transaction management, and they comply with Spring's generic
    transaction and DAO exception hierarchies. The recommended integration
    style is to code DAOs against plain Hibernate, JPA, and JDO APIs. The
    older style of using Spring's DAO templates is no longer recommended;
    however, coverage of this style can be found in the <a class="xref" href="classic-spring.html#classic-spring-orm" title="A.1&nbsp;Classic ORM usage">Section&nbsp;A.1, &#8220;Classic ORM usage&#8221;</a> in the appendices.</p><p>Spring adds significant enhancements to the ORM layer of your choice
    when you create data access applications. You can leverage as much of the
    integration support as you wish, and you should compare this integration
    effort with the cost and risk of building a similar infrastructure
    in-house. You can use much of the ORM support as you would a library,
    regardless of technology, because everything is designed as a set of
    reusable JavaBeans. ORM in a Spring IoC container facilitates
    configuration and deployment. Thus most examples in this section show
    configuration inside a Spring container.</p><p>Benefits of using the Spring Framework to create your ORM DAOs
    include:</p><div class="itemizedlist"><ul type="disc"><li><p><span class="emphasis"><em>Easier testing.</em></span> Spring's IoC approach makes
        it easy to swap the implementations and configuration locations of
        Hibernate <code class="interfacename">SessionFactory</code> instances,
        JDBC <code class="interfacename">DataSource</code> instances, transaction
        managers, and mapped object implementations (if needed). This in turn makes it
        much easier to test each piece of persistence-related code in
        isolation.</p></li><li><p><span class="emphasis"><em>Common data access exceptions.</em></span> Spring can
        wrap exceptions from your ORM tool, converting them from proprietary
        (potentially checked) exceptions to a common runtime
        DataAccessException hierarchy. This feature allows you to handle most
        persistence exceptions, which are non-recoverable, only in the
        appropriate layers, without annoying boilerplate catches, throws, and
        exception declarations. You can still trap and handle exceptions as
        necessary. Remember that JDBC exceptions (including DB-specific
        dialects) are also converted to the same hierarchy, meaning that you
        can perform some operations with JDBC within a consistent programming
        model.</p></li><li><p><span class="emphasis"><em>General resource management.</em></span> Spring
        application contexts can handle the location and configuration of
        Hibernate <code class="interfacename">SessionFactory</code> instances, JPA
        <code class="interfacename">EntityManagerFactory</code> instances, JDBC
        <code class="interfacename">DataSource</code> instances, iBATIS SQL Maps
        configuration objects, and other related resources. This makes these
        values easy to manage and change. Spring offers efficient, easy, and
        safe handling of persistence resources. For example, related code that
        uses Hibernate generally needs to use the same Hibernate
        <code class="interfacename">Session</code> to ensure efficiency and proper
        transaction handling. Spring makes it easy to create and bind a
        <code class="interfacename">Session</code> to the current thread
        transparently, by
        exposing a current <code class="interfacename">Session</code> through the
        Hibernate <code class="interfacename">SessionFactory</code>. Thus Spring
        solves many chronic problems of typical Hibernate usage, for any local
        or JTA transaction environment.</p></li><li><p><span class="emphasis"><em>Integrated transaction management.</em></span> You can
        wrap your ORM code with a declarative, aspect-oriented programming
        (AOP) style method interceptor either through the
        <code class="interfacename">@Transactional</code> annotation or by
        explicitly configuring the transaction AOP advice in an XML
        configuration file. In both cases, transaction semantics and exception
        handling (rollback, and so on) are handled for you. As discussed
        below, in <a class="link" href="orm.html#orm-resource-mngmnt" title="13.2.1&nbsp;Resource and transaction management">Resource and transaction
        management</a>, you can also swap various transaction managers,
        without affecting your ORM-related code. For example, you can swap
        between local transactions and JTA, with the same full services (such
        as declarative transactions) available in both scenarios.
        Additionally, JDBC-related code can fully integrate transactionally
        with the code you use to do ORM. This is useful for data access that
        is not suitable for ORM, such as batch processing and BLOB streaming,
        which still need to
        share common transactions with ORM operations.</p></li></ul></div><p><span class="emphasis"><em>TODO:
    provide links to current samples</em></span></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="orm-general"></a>13.2&nbsp;General ORM integration considerations</h2></div></div></div><p>This section highlights considerations that apply to all ORM
    technologies. The <a class="xref" href="orm.html#orm-hibernate" title="13.3&nbsp;Hibernate">Section&nbsp;13.3, &#8220;Hibernate&#8221;</a> section provides more
    details and also show these features and configurations in a concrete
    context.</p><p>The major goal of Spring's ORM integration is clear application
    layering, with any data access and transaction technology, and for loose
    coupling of application objects. No more business service dependencies on
    the data access or transaction strategy, no more hard-coded resource
    lookups, no more hard-to-replace singletons, no more custom service
    registries. One simple and consistent approach to wiring up application
    objects, keeping them as reusable and free from container dependencies as
    possible. All the individual data access features are usable on their own
    but integrate nicely with Spring's application context concept, providing
    XML-based configuration and cross-referencing of plain JavaBean instances
    that need not be Spring-aware. In a typical Spring application, many
    important objects are JavaBeans: data access templates, data access
    objects, transaction managers, business services that use the data access
    objects and transaction managers, web view resolvers, web controllers that
    use the business services,and so on.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="orm-resource-mngmnt"></a>13.2.1&nbsp;Resource and transaction management</h3></div></div></div><p>Typical business applications are cluttered with repetitive
      resource management code. Many projects try to invent their own
      solutions, sometimes sacrificing proper handling of failures for
      programming convenience. Spring advocates simple solutions for proper
      resource handling, namely IoC through templating in the case of
      JDBC and applying AOP interceptors for the ORM technologies.</p><p>The infrastructure provides proper resource handling and
      appropriate conversion of specific API exceptions to an unchecked
      infrastructure exception hierarchy. Spring
      introduces a DAO exception hierarchy, applicable to any data access
      strategy. For direct JDBC, the <code class="classname">JdbcTemplate</code> class
      mentioned in a previous section provides connection handling and proper
      conversion of <code class="classname">SQLException</code> to the
      <code class="classname">DataAccessException</code> hierarchy, including
      translation of database-specific SQL error codes to meaningful exception
      classes. For ORM technologies, see the next section for how to get the
      same exception translation benefits.</p><p>When it comes to transaction management, the
      <code class="classname">JdbcTemplate</code> class hooks in to the Spring
      transaction support and supports both JTA and JDBC transactions, through
      respective Spring transaction managers. For the supported ORM
      technologies Spring offers Hibernate, JPA and JDO support through the
      Hibernate, JPA, and JDO transaction managers as well as JTA support. For
      details on transaction support, see the <a class="xref" href="transaction.html" title="10.&nbsp;Transaction Management">Chapter&nbsp;10, <i>Transaction Management</i></a>
      chapter.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="orm-exception-translation"></a>13.2.2&nbsp;Exception translation</h3></div></div></div><p>When you use Hibernate, JPA, or JDO in a DAO, you must decide how
      to handle the persistence technology's native exception classes. The DAO
      throws a subclass of a <code class="classname">HibernateException</code>,
      <code class="classname">PersistenceException</code> or
      <code class="interfacename">JDOException</code> depending on the technology.
      These exceptions are all run-time exceptions and do not have to be
      declared or caught. You may also have to deal with
      <code class="classname">IllegalArgumentException</code> and
      <code class="classname">IllegalStateException</code>. This means that callers
      can only treat exceptions as generally fatal, unless they want to depend
      on the persistence technology's own exception structure. Catching
      specific causes such as an optimistic locking failure is not possible
      without tying the caller to the implementation strategy. This trade off
      might be acceptable to applications that are strongly ORM-based and/or
      do not need any special exception treatment. However, Spring enables
      exception translation to be applied transparently through the
      <code class="interfacename">@Repository</code> annotation:</p><pre class="programlisting">@Repository
<span class="hl-keyword">public</span> <span class="hl-keyword">class</span> ProductDaoImpl <span class="hl-keyword">implements</span> ProductDao {

    <span class="hl-comment">// class body here...</span>

}</pre><pre class="programlisting">&lt;<span class="hl-tag">beans</span>&gt;

  &lt;<span class="hl-comment">!-- Exception translation bean post processor --</span>&gt;
  &lt;<span class="hl-tag">bean</span> <span class="hl-attribute">class</span>=<span class="hl-value">"org.springframework.dao.annotation.PersistenceExceptionTranslationPostProcessor"</span>/&gt;

  &lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"myProductDao"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"product.ProductDaoImpl"</span>/&gt;

&lt;<span class="hl-tag">/beans</span>&gt;</pre><p>The postprocessor automatically looks for all exception
      translators (implementations of the
      <code class="interfacename">PersistenceExceptionTranslator</code> interface)
      and advises all beans marked with the
      <code class="interfacename">@Repository</code> annotation so that the
      discovered translators can intercept and apply the appropriate
      translation on the thrown exceptions.</p><p>In summary: you can implement DAOs based on the plain persistence
      technology's API and annotations, while still benefiting from
      Spring-managed transactions, dependency injection, and transparent
      exception conversion (if desired) to Spring's custom exception
      hierarchies.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="orm-hibernate"></a>13.3&nbsp;Hibernate</h2></div></div></div><p>We will start with a coverage of <a class="ulink" href="http://www.hibernate.org/" target="_top">Hibernate 3</a> in a Spring
    environment, using it to demonstrate the approach that Spring takes
    towards integrating O/R mappers. This section will cover many issues in
    detail and show different variations of DAO implementations and
    transaction demarcation. Most of these patterns can be directly translated
    to all other supported ORM tools. The following sections in this chapter
    will then cover the other ORM technologies, showing briefer examples
    there.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.gif"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>As of Spring 3.0, Spring requires Hibernate 3.2 or later.</p></td></tr></table></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="orm-session-factory-setup"></a>13.3.1&nbsp;<code class="interfacename">SessionFactory</code> setup in a Spring
      container</h3></div></div></div><p>To avoid tying application objects to hard-coded resource lookups,
      you can define resources such as a JDBC
      <code class="interfacename">DataSource</code> or a Hibernate
      <code class="interfacename">SessionFactory</code> as beans in the Spring
      container. Application objects that need to access resources receive
      references to such predefined instances through bean references, as
      illustrated in the DAO definition in the next section.</p><p>The following excerpt from an XML application context definition
      shows how to set up a JDBC <code class="classname">DataSource</code> and a
      Hibernate <code class="interfacename">SessionFactory</code> on top of
      it:</p><pre class="programlisting">&lt;<span class="hl-tag">beans</span>&gt;

  &lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"myDataSource"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"org.apache.commons.dbcp.BasicDataSource"</span> <span class="hl-attribute">destroy-method</span>=<span class="hl-value">"close"</span>&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"driverClassName"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"org.hsqldb.jdbcDriver"</span>/&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"url"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"jdbc:hsqldb:hsql://localhost:9001"</span>/&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"username"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"sa"</span>/&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"password"</span> <span class="hl-attribute">value</span>=<span class="hl-value">""</span>/&gt;
  &lt;<span class="hl-tag">/bean</span>&gt;

  &lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"mySessionFactory"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"org.springframework.orm.hibernate3.LocalSessionFactoryBean"</span>&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"dataSource"</span> <span class="hl-attribute">ref</span>=<span class="hl-value">"myDataSource"</span>/&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"mappingResources"</span>&gt;
      &lt;<span class="hl-tag">list</span>&gt;
        &lt;<span class="hl-tag">value</span>&gt;product.hbm.xml&lt;<span class="hl-tag">/value</span>&gt;
      &lt;<span class="hl-tag">/list</span>&gt;
    &lt;<span class="hl-tag">/property</span>&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"hibernateProperties"</span>&gt;
      &lt;<span class="hl-tag">value</span>&gt;
        hibernate.dialect=org.hibernate.dialect.HSQLDialect
      &lt;<span class="hl-tag">/value</span>&gt;
    &lt;<span class="hl-tag">/property</span>&gt;
  &lt;<span class="hl-tag">/bean</span>&gt;

&lt;<span class="hl-tag">/beans</span>&gt;</pre><p>Switching from a local Jakarta Commons DBCP
      <code class="classname">BasicDataSource</code> to a JNDI-located
      <code class="interfacename">DataSource</code> (usually managed by an
      application server) is just a matter of configuration:</p><pre class="programlisting">&lt;<span class="hl-tag">beans</span>&gt;

  &lt;<span class="hl-tag">jee:jndi-lookup</span> <span class="hl-attribute">id</span>=<span class="hl-value">"myDataSource"</span> <span class="hl-attribute">jndi-name</span>=<span class="hl-value">"java:comp/env/jdbc/myds"</span>/&gt;

&lt;<span class="hl-tag">/beans</span>&gt;</pre><p>You can also access a JNDI-located
      <code class="interfacename">SessionFactory</code>, using Spring's
      <code class="classname">JndiObjectFactoryBean</code> /
      <code class="literal">&lt;jee:jndi-lookup&gt;</code> to retrieve and expose it.
      However, that is typically not common outside of an EJB context.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="orm-hibernate-straight"></a>13.3.2&nbsp;Implementing DAOs based on plain Hibernate 3 API</h3></div></div></div><p>Hibernate 3 has a feature called contextual sessions, wherein
      Hibernate itself manages one current
      <code class="interfacename">Session</code> per transaction. This is roughly
      equivalent to Spring's synchronization of one Hibernate
      <code class="interfacename">Session</code> per transaction. A corresponding
      DAO implementation resembles the following example, based on the plain
      Hibernate API:</p><pre class="programlisting"><span class="hl-keyword">public</span> <span class="hl-keyword">class</span> ProductDaoImpl <span class="hl-keyword">implements</span> ProductDao {

    <span class="hl-keyword">private</span> SessionFactory sessionFactory;

    <span class="hl-keyword">public</span> <span class="hl-keyword">void</span> setSessionFactory(SessionFactory sessionFactory) {
        <span class="hl-keyword">this</span>.sessionFactory = sessionFactory;
    }

    <span class="hl-keyword">public</span> Collection loadProductsByCategory(String category) {
        <span class="hl-keyword">return</span> <span class="hl-keyword">this</span>.sessionFactory.getCurrentSession()
                .createQuery(<span class="hl-string">"from test.Product product where product.category=?"</span>)
                .setParameter(0, category)
                .list();
    }
}</pre><p>This style is similar to that of the Hibernate reference
      documentation and examples, except for holding the
      <code class="interfacename">SessionFactory</code> in an instance variable.
      We strongly recommend such an instance-based setup over the old-school
      <code class="literal">static</code> <code class="classname">HibernateUtil</code> class
      from Hibernate's CaveatEmptor sample application. (In general, do not
      keep any resources in <code class="literal">static</code> variables unless
      <span class="emphasis"><em>absolutely</em></span> necessary.)</p><p>The above DAO follows the dependency injection pattern: it fits
      nicely into a Spring IoC container, just as it would if coded against
      Spring's <code class="classname">HibernateTemplate</code>. Of course, such a DAO
      can also be set up in plain Java (for example, in unit tests). Simply
      instantiate it and call <code class="methodname">setSessionFactory(..)</code>
      with the desired factory reference. As a Spring bean definition, the DAO
      would resemble the following:</p><pre class="programlisting">&lt;<span class="hl-tag">beans</span>&gt;

  &lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"myProductDao"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"product.ProductDaoImpl"</span>&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"sessionFactory"</span> <span class="hl-attribute">ref</span>=<span class="hl-value">"mySessionFactory"</span>/&gt;
  &lt;<span class="hl-tag">/bean</span>&gt;

&lt;<span class="hl-tag">/beans</span>&gt;</pre><p>The main advantage of this DAO style is that it depends on
      Hibernate API only; no import of any Spring class is required. This is
      of course appealing from a non-invasiveness perspective, and will no
      doubt feel more natural to Hibernate developers.</p><p>However, the DAO throws plain
      <code class="classname">HibernateException</code> (which is unchecked, so does
      not have to be declared or caught), which means that callers can only
      treat exceptions as generally fatal - unless they want to depend on
      Hibernate's own exception hierarchy. Catching specific causes such as an
      optimistic locking failure is not possible without tying the caller to
      the implementation strategy. This trade off might be acceptable to
      applications that are strongly Hibernate-based and/or do not need any
      special exception treatment.</p><p>Fortunately, Spring's
      <code class="classname">LocalSessionFactoryBean</code> supports Hibernate's
      <code class="methodname">SessionFactory.getCurrentSession()</code> method for
      any Spring transaction strategy, returning the current Spring-managed
      transactional <code class="interfacename">Session</code> even with
      <code class="classname">HibernateTransactionManager</code>. Of course, the
      standard behavior of that method remains the return of the current
      <code class="interfacename">Session</code> associated with the ongoing JTA
      transaction, if any. This behavior applies regardless of whether you are
      using Spring's <code class="classname">JtaTransactionManager</code>, EJB
      container managed transactions (CMTs), or JTA.</p><p>In summary: you can implement DAOs based on the plain Hibernate 3
      API, while still being able to participate in Spring-managed
      transactions.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="orm-hibernate-tx-declarative"></a>13.3.3&nbsp;Declarative transaction demarcation</h3></div></div></div><p>We recommend that you use Spring's declarative transaction
      support, which enables you to replace explicit transaction demarcation
      API calls in your Java code with an AOP transaction interceptor. This
      transaction interceptor can be configured in a Spring container using
      either Java annotations or XML.This declarative transaction capability allows you
      to keep business services free of repetitive transaction demarcation
      code and to focus on adding business logic, which is the real value of
      your application.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.gif"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Prior to continuing, you are <span class="emphasis"><em>strongly</em></span>
        encouraged to read <a class="xref" href="transaction.html#transaction-declarative" title="10.5&nbsp;Declarative transaction management">Section&nbsp;10.5, &#8220;Declarative transaction management&#8221;</a> if you
        have not done so.</p></td></tr></table></div><p>Furthermore, transaction semantics like propagation behavior and
      isolation level can be changed in a configuration file and do not affect
      the business service implementations.</p><p>The following example shows how you can configure an AOP
      transaction interceptor, using XML, for a simple service class:</p><pre class="programlisting">&lt;<span class="hl-tag">?xml version="1.0" encoding="UTF-8"?</span>&gt;
&lt;<span class="hl-tag">beans</span> <span class="hl-attribute">xmlns</span>=<span class="hl-value">"http://www.springframework.org/schema/beans"</span>
       <span class="hl-attribute">xmlns:xsi</span>=<span class="hl-value">"http://www.w3.org/2001/XMLSchema-instance"</span>
       <span class="hl-attribute">xmlns:aop</span>=<span class="hl-value">"http://www.springframework.org/schema/aop"</span>
       <span class="hl-attribute">xmlns:tx</span>=<span class="hl-value">"http://www.springframework.org/schema/tx"</span>
       <span class="hl-attribute">xsi:schemaLocation</span>=<span class="hl-value">"
       http://www.springframework.org/schema/beans 
       http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
       http://www.springframework.org/schema/tx 
       http://www.springframework.org/schema/tx/spring-tx-3.0.xsd
       http://www.springframework.org/schema/aop 
       http://www.springframework.org/schema/aop/spring-aop-3.0.xsd"</span>&gt;

  &lt;<span class="hl-comment">!-- SessionFactory, DataSource, etc. omitted --</span>&gt;

  &lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"transactionManager"</span> 
            <span class="hl-attribute">class</span>=<span class="hl-value">"org.springframework.orm.hibernate3.HibernateTransactionManager"</span>&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"sessionFactory"</span> <span class="hl-attribute">ref</span>=<span class="hl-value">"sessionFactory"</span>/&gt;
  &lt;<span class="hl-tag">/bean</span>&gt;
  
  &lt;<span class="hl-tag">aop:config</span>&gt;
    &lt;<span class="hl-tag">aop:pointcut</span> <span class="hl-attribute">id</span>=<span class="hl-value">"productServiceMethods"</span> 
            <span class="hl-attribute">expression</span>=<span class="hl-value">"execution(* product.ProductService.*(..))"</span>/&gt;
    &lt;<span class="hl-tag">aop:advisor</span> <span class="hl-attribute">advice-ref</span>=<span class="hl-value">"txAdvice"</span> <span class="hl-attribute">pointcut-ref</span>=<span class="hl-value">"productServiceMethods"</span>/&gt;
  &lt;<span class="hl-tag">/aop:config</span>&gt;

  &lt;<span class="hl-tag">tx:advice</span> <span class="hl-attribute">id</span>=<span class="hl-value">"txAdvice"</span> <span class="hl-attribute">transaction-manager</span>=<span class="hl-value">"myTxManager"</span>&gt;
    &lt;<span class="hl-tag">tx:attributes</span>&gt;
      &lt;<span class="hl-tag">tx:method</span> <span class="hl-attribute">name</span>=<span class="hl-value">"increasePrice*"</span> <span class="hl-attribute">propagation</span>=<span class="hl-value">"REQUIRED"</span>/&gt;
      &lt;<span class="hl-tag">tx:method</span> <span class="hl-attribute">name</span>=<span class="hl-value">"someOtherBusinessMethod"</span> <span class="hl-attribute">propagation</span>=<span class="hl-value">"REQUIRES_NEW"</span>/&gt;
      &lt;<span class="hl-tag">tx:method</span> <span class="hl-attribute">name</span>=<span class="hl-value">"*"</span> <span class="hl-attribute">propagation</span>=<span class="hl-value">"SUPPORTS"</span> <span class="hl-attribute">read-only</span>=<span class="hl-value">"true"</span>/&gt;
    &lt;<span class="hl-tag">/tx:attributes</span>&gt;
  &lt;<span class="hl-tag">/tx:advice</span>&gt;

  &lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"myProductService"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"product.SimpleProductService"</span>&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"productDao"</span> <span class="hl-attribute">ref</span>=<span class="hl-value">"myProductDao"</span>/&gt;
  &lt;<span class="hl-tag">/bean</span>&gt;

&lt;<span class="hl-tag">/beans</span>&gt;</pre><p>This is the service class that is advised:</p><pre class="programlisting"><span class="hl-keyword">public</span> <span class="hl-keyword">class</span> ProductServiceImpl <span class="hl-keyword">implements</span> ProductService {

    <span class="hl-keyword">private</span> ProductDao productDao;

    <span class="hl-keyword">public</span> <span class="hl-keyword">void</span> setProductDao(ProductDao productDao) {
        <span class="hl-keyword">this</span>.productDao = productDao;
    }

    <span class="hl-comment">// notice the absence of transaction demarcation code in this method</span>
    <span class="hl-comment">// Spring's declarative transaction infrastructure will be demarcating</span>
    <span class="hl-comment">// transactions on your behalf </span>
    <span class="hl-keyword">public</span> <span class="hl-keyword">void</span> increasePriceOfAllProductsInCategory(<span class="hl-keyword">final</span> String category) {
        List productsToChange = <span class="hl-keyword">this</span>.productDao.loadProductsByCategory(category);
        <span class="hl-comment">// ...</span>
    }
}</pre><p>We also show an attribute-support based configuration, in the
      following example. You
      annotate the service layer with @Transactional annotations and instruct
      the Spring container to find these annotations and provide transactional
      semantics for these annotated methods.</p><pre class="programlisting"><span class="hl-keyword">public</span> <span class="hl-keyword">class</span> ProductServiceImpl <span class="hl-keyword">implements</span> ProductService {

    <span class="hl-keyword">private</span> ProductDao productDao;

    <span class="hl-keyword">public</span> <span class="hl-keyword">void</span> setProductDao(ProductDao productDao) {
        <span class="hl-keyword">this</span>.productDao = productDao;
    }

    @Transactional
    <span class="hl-keyword">public</span> <span class="hl-keyword">void</span> increasePriceOfAllProductsInCategory(<span class="hl-keyword">final</span> String category) {
        List productsToChange = <span class="hl-keyword">this</span>.productDao.loadProductsByCategory(category);
        <span class="hl-comment">// ...</span>
    }

    @Transactional(readOnly = true)
    <span class="hl-keyword">public</span> List&lt;Product&gt; findAllProducts() {
        <span class="hl-keyword">return</span> <span class="hl-keyword">this</span>.productDao.findAllProducts();
    }

}</pre><p>As you can see from the following configuration example, the
      configuration is much simplified, compared to the XML example above,
      while still providing the same functionality driven by the annotations
      in the service layer code. All you need to provide is the
      TransactionManager implementation and a "&lt;tx:annotation-driven/&gt;"
      entry.</p><pre class="programlisting">&lt;<span class="hl-tag">?xml version="1.0" encoding="UTF-8"?</span>&gt;
&lt;<span class="hl-tag">beans</span> <span class="hl-attribute">xmlns</span>=<span class="hl-value">"http://www.springframework.org/schema/beans"</span>
       <span class="hl-attribute">xmlns:xsi</span>=<span class="hl-value">"http://www.w3.org/2001/XMLSchema-instance"</span>
       <span class="hl-attribute">xmlns:aop</span>=<span class="hl-value">"http://www.springframework.org/schema/aop"</span>
       <span class="hl-attribute">xmlns:tx</span>=<span class="hl-value">"http://www.springframework.org/schema/tx"</span>
       <span class="hl-attribute">xsi:schemaLocation</span>=<span class="hl-value">"
       http://www.springframework.org/schema/beans 
       http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
       http://www.springframework.org/schema/tx 
       http://www.springframework.org/schema/tx/spring-tx-3.0.xsd
       http://www.springframework.org/schema/aop 
       http://www.springframework.org/schema/aop/spring-aop-3.0.xsd"</span>&gt;

  &lt;<span class="hl-comment">!-- SessionFactory, DataSource, etc. omitted --</span>&gt;

  &lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"transactionManager"</span>
            <span class="hl-attribute">class</span>=<span class="hl-value">"org.springframework.orm.hibernate3.HibernateTransactionManager"</span>&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"sessionFactory"</span> <span class="hl-attribute">ref</span>=<span class="hl-value">"sessionFactory"</span>/&gt;
  &lt;<span class="hl-tag">/bean</span>&gt;
  
  &lt;<span class="hl-tag">tx:annotation-driven</span>/&gt;

  &lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"myProductService"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"product.SimpleProductService"</span>&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"productDao"</span> <span class="hl-attribute">ref</span>=<span class="hl-value">"myProductDao"</span>/&gt;
  &lt;<span class="hl-tag">/bean</span>&gt;

&lt;<span class="hl-tag">/beans</span>&gt;</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="orm-hibernate-tx-programmatic"></a>13.3.4&nbsp;Programmatic transaction demarcation</h3></div></div></div><p>You can demarcate transactions in a higher level of the
      application, on top of such lower-level data access services spanning
      any number of operations. Nor do restrictions exist on the
      implementation of the surrounding business service; it just needs a
      Spring <code class="classname">PlatformTransactionManager</code>. Again, the
      latter can come from anywhere, but preferably as a bean reference
      through a <code class="methodname">setTransactionManager(..)</code> method,
      just as the <code class="classname">productDAO</code> should be set by a
      <code class="methodname">setProductDao(..)</code> method. The following
      snippets show a transaction manager and a business service definition in
      a Spring application context, and an example for a business method
      implementation:</p><pre class="programlisting">&lt;<span class="hl-tag">beans</span>&gt;

  &lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"myTxManager"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"org.springframework.orm.hibernate3.HibernateTransactionManager"</span>&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"sessionFactory"</span> <span class="hl-attribute">ref</span>=<span class="hl-value">"mySessionFactory"</span>/&gt;
  &lt;<span class="hl-tag">/bean</span>&gt;

  &lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"myProductService"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"product.ProductServiceImpl"</span>&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"transactionManager"</span> <span class="hl-attribute">ref</span>=<span class="hl-value">"myTxManager"</span>/&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"productDao"</span> <span class="hl-attribute">ref</span>=<span class="hl-value">"myProductDao"</span>/&gt;
  &lt;<span class="hl-tag">/bean</span>&gt;

&lt;<span class="hl-tag">/beans</span>&gt;</pre><pre class="programlisting"><span class="hl-keyword">public</span> <span class="hl-keyword">class</span> ProductServiceImpl <span class="hl-keyword">implements</span> ProductService {

    <span class="hl-keyword">private</span> TransactionTemplate transactionTemplate;
    <span class="hl-keyword">private</span> ProductDao productDao;

    <span class="hl-keyword">public</span> <span class="hl-keyword">void</span> setTransactionManager(PlatformTransactionManager transactionManager) {
        <span class="hl-keyword">this</span>.transactionTemplate = <span class="hl-keyword">new</span> TransactionTemplate(transactionManager);
    }

    <span class="hl-keyword">public</span> <span class="hl-keyword">void</span> setProductDao(ProductDao productDao) {
        <span class="hl-keyword">this</span>.productDao = productDao;
    }

    <span class="hl-keyword">public</span> <span class="hl-keyword">void</span> increasePriceOfAllProductsInCategory(<span class="hl-keyword">final</span> String category) {
        <span class="hl-keyword">this</span>.transactionTemplate.execute(<span class="hl-keyword">new</span> TransactionCallbackWithoutResult() {

                <span class="hl-keyword">public</span> <span class="hl-keyword">void</span> doInTransactionWithoutResult(TransactionStatus status) {
                    List productsToChange = <span class="hl-keyword">this</span>.productDao.loadProductsByCategory(category);
                    <span class="hl-comment">// do the price increase...</span>
                }
            }
        );
    }
}</pre><p>Spring's <code class="classname">TransactionInterceptor</code> allows any
      checked application exception to be thrown with the callback code, while
      <code class="classname">TransactionTemplate</code> is restricted to unchecked
      exceptions within the callback.
      <code class="classname">TransactionTemplate</code> triggers a rollback in case
      of an unchecked application exception, or if the transaction is marked
      rollback-only by the application (via
      <code class="classname">TransactionStatus</code>).
      <code class="classname">TransactionInterceptor</code> behaves the same way by
      default but allows configurable rollback policies per method.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="orm-hibernate-tx-strategies"></a>13.3.5&nbsp;Transaction management strategies</h3></div></div></div><p>Both <code class="classname">TransactionTemplate</code> and
      <code class="classname">TransactionInterceptor</code> delegate the actual
      transaction handling to a
      <code class="classname">PlatformTransactionManager</code> instance, which can be
      a <code class="classname">HibernateTransactionManager</code> (for a single
      Hibernate <code class="interfacename">SessionFactory</code>, using a
      <code class="classname">ThreadLocal</code>
      <code class="interfacename">Session</code> under the hood) or a
      <code class="classname">JtaTransactionManager</code> (delegating to the JTA
      subsystem of the container) for Hibernate applications. You can even use
      a custom <code class="classname">PlatformTransactionManager</code>
      implementation. Switching from native Hibernate transaction management
      to JTA, such as when facing distributed transaction requirements for
      certain deployments of your application, is just a matter of
      configuration. Simply replace the Hibernate transaction manager with
      Spring's JTA transaction implementation. Both transaction demarcation
      and data access code will work without changes, because they just use
      the generic transaction management APIs.</p><p>For distributed transactions across multiple Hibernate session
      factories, simply combine <code class="classname">JtaTransactionManager</code>
      as a transaction strategy with multiple
      <code class="classname">LocalSessionFactoryBean</code> definitions. Each DAO
      then gets one specific <code class="interfacename">SessionFactory</code>
      reference passed into its corresponding bean property. If all underlying
      JDBC data sources are transactional container ones, a business service
      can demarcate transactions across any number of DAOs and any number of
      session factories without special regard, as long as it is using
      <code class="classname">JtaTransactionManager</code> as the strategy.</p><pre class="programlisting">&lt;<span class="hl-tag">beans</span>&gt;

  &lt;<span class="hl-tag">jee:jndi-lookup</span> <span class="hl-attribute">id</span>=<span class="hl-value">"dataSource1"</span> <span class="hl-attribute">jndi-name</span>=<span class="hl-value">"java:comp/env/jdbc/myds1"</span>/&gt;

  &lt;<span class="hl-tag">jee:jndi-lookup</span> <span class="hl-attribute">id</span>=<span class="hl-value">"dataSource2"</span> <span class="hl-attribute">jndi-name</span>=<span class="hl-value">"java:comp/env/jdbc/myds2"</span>/&gt;

  &lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"mySessionFactory1"</span>
            <span class="hl-attribute">class</span>=<span class="hl-value">"org.springframework.orm.hibernate3.LocalSessionFactoryBean"</span>&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"dataSource"</span> <span class="hl-attribute">ref</span>=<span class="hl-value">"myDataSource1"</span>/&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"mappingResources"</span>&gt;
      &lt;<span class="hl-tag">list</span>&gt;
        &lt;<span class="hl-tag">value</span>&gt;product.hbm.xml&lt;<span class="hl-tag">/value</span>&gt;
      &lt;<span class="hl-tag">/list</span>&gt;
    &lt;<span class="hl-tag">/property</span>&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"hibernateProperties"</span>&gt;
      &lt;<span class="hl-tag">value</span>&gt;
        hibernate.dialect=org.hibernate.dialect.MySQLDialect
        hibernate.show_sql=true
      &lt;<span class="hl-tag">/value</span>&gt;
    &lt;<span class="hl-tag">/property</span>&gt;
  &lt;<span class="hl-tag">/bean</span>&gt;

  &lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"mySessionFactory2"</span>
            <span class="hl-attribute">class</span>=<span class="hl-value">"org.springframework.orm.hibernate3.LocalSessionFactoryBean"</span>&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"dataSource"</span> <span class="hl-attribute">ref</span>=<span class="hl-value">"myDataSource2"</span>/&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"mappingResources"</span>&gt;
      &lt;<span class="hl-tag">list</span>&gt;
        &lt;<span class="hl-tag">value</span>&gt;inventory.hbm.xml&lt;<span class="hl-tag">/value</span>&gt;
      &lt;<span class="hl-tag">/list</span>&gt;
    &lt;<span class="hl-tag">/property</span>&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"hibernateProperties"</span>&gt;
      &lt;<span class="hl-tag">value</span>&gt;
        hibernate.dialect=org.hibernate.dialect.OracleDialect
      &lt;<span class="hl-tag">/value</span>&gt;
    &lt;<span class="hl-tag">/property</span>&gt;
  &lt;<span class="hl-tag">/bean</span>&gt;

  &lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"myTxManager"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"org.springframework.transaction.jta.JtaTransactionManager"</span>/&gt;

  &lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"myProductDao"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"product.ProductDaoImpl"</span>&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"sessionFactory"</span> <span class="hl-attribute">ref</span>=<span class="hl-value">"mySessionFactory1"</span>/&gt;
  &lt;<span class="hl-tag">/bean</span>&gt;

  &lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"myInventoryDao"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"product.InventoryDaoImpl"</span>&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"sessionFactory"</span> <span class="hl-attribute">ref</span>=<span class="hl-value">"mySessionFactory2"</span>/&gt;
  &lt;<span class="hl-tag">/bean</span>&gt;

  &lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"myProductService"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"product.ProductServiceImpl"</span>&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"productDao"</span> <span class="hl-attribute">ref</span>=<span class="hl-value">"myProductDao"</span>/&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"inventoryDao"</span> <span class="hl-attribute">ref</span>=<span class="hl-value">"myInventoryDao"</span>/&gt;
  &lt;<span class="hl-tag">/bean</span>&gt;

  &lt;<span class="hl-tag">aop:config</span>&gt;
    &lt;<span class="hl-tag">aop:pointcut</span> <span class="hl-attribute">id</span>=<span class="hl-value">"productServiceMethods"</span>
                <span class="hl-attribute">expression</span>=<span class="hl-value">"execution(* product.ProductService.*(..))"</span>/&gt;
    &lt;<span class="hl-tag">aop:advisor</span> <span class="hl-attribute">advice-ref</span>=<span class="hl-value">"txAdvice"</span> <span class="hl-attribute">pointcut-ref</span>=<span class="hl-value">"productServiceMethods"</span>/&gt;
  &lt;<span class="hl-tag">/aop:config</span>&gt;

  &lt;<span class="hl-tag">tx:advice</span> <span class="hl-attribute">id</span>=<span class="hl-value">"txAdvice"</span> <span class="hl-attribute">transaction-manager</span>=<span class="hl-value">"myTxManager"</span>&gt;
    &lt;<span class="hl-tag">tx:attributes</span>&gt;
      &lt;<span class="hl-tag">tx:method</span> <span class="hl-attribute">name</span>=<span class="hl-value">"increasePrice*"</span> <span class="hl-attribute">propagation</span>=<span class="hl-value">"REQUIRED"</span>/&gt;
      &lt;<span class="hl-tag">tx:method</span> <span class="hl-attribute">name</span>=<span class="hl-value">"someOtherBusinessMethod"</span> <span class="hl-attribute">propagation</span>=<span class="hl-value">"REQUIRES_NEW"</span>/&gt;
      &lt;<span class="hl-tag">tx:method</span> <span class="hl-attribute">name</span>=<span class="hl-value">"*"</span> <span class="hl-attribute">propagation</span>=<span class="hl-value">"SUPPORTS"</span> <span class="hl-attribute">read-only</span>=<span class="hl-value">"true"</span>/&gt;
    &lt;<span class="hl-tag">/tx:attributes</span>&gt;
  &lt;<span class="hl-tag">/tx:advice</span>&gt;

&lt;<span class="hl-tag">/beans</span>&gt;</pre><p>Both <code class="classname">HibernateTransactionManager</code> and
      <code class="classname">JtaTransactionManager</code> allow for proper JVM-level
      cache handling with Hibernate, without container-specific transaction
      manager lookup or a JCA connector (if you are not using EJB to initiate
      transactions).</p><p><code class="classname">HibernateTransactionManager</code> can export the
      Hibernate JDBC <code class="interfacename">Connection</code> to plain JDBC
      access code, for a specific <code class="interfacename">DataSource</code>.
      This capability allows for high-level transaction demarcation with mixed
      Hibernate and JDBC data access completely without JTA, if you are
      accessing only one database.
      <code class="classname">HibernateTransactionManager</code> automatically exposes
      the Hibernate transaction as a JDBC transaction if you have set up the
      passed-in <code class="interfacename">SessionFactory</code> with a
      <code class="interfacename">DataSource</code> through the
      <code class="classname">dataSource</code> property of the
      <code class="classname">LocalSessionFactoryBean</code> class. Alternatively, you
      can specify explicitly the <code class="interfacename">DataSource</code> for
      which the transactions are supposed to be exposed through the
      <code class="classname">dataSource</code> property of the
      <code class="classname">HibernateTransactionManager</code> class.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="orm-hibernate-resources"></a>13.3.6&nbsp;Comparing container-managed and locally defined resources</h3></div></div></div><p>You can switch between a container-managed JNDI
      <code class="interfacename">SessionFactory</code> and a
      locally defined one, without having to change a single line of
      application code. Whether to keep resource definitions in the container
      or locally within the application is mainly a matter of the transaction
      strategy that you use. Compared to a Spring-defined local
      <code class="interfacename">SessionFactory</code>, a manually registered
      JNDI <code class="interfacename">SessionFactory</code> does not provide any
      benefits. Deploying a <code class="interfacename">SessionFactory</code>
      through Hibernate's JCA connector provides the added value of
      participating in the Java EE server's management infrastructure, but
      does not add actual value beyond that.</p><p>Spring's transaction support is not bound to a container.
      Configured with any strategy other than JTA, transaction support also
      works in a stand-alone or test environment. Especially in the typical
      case of single-database transactions, Spring's single-resource local
      transaction support is
      a lightweight and powerful alternative to JTA. When you use local EJB
      stateless session beans to drive transactions, you depend both on an EJB
      container and JTA, even if you access only a single database, and only
      use stateless session beans to provide declarative transactions through
      container-managed transactions. Also,
      direct use of JTA programmatically requires a Java EE environment as
      well. JTA does not involve only container dependencies in terms of JTA
      itself and of JNDI <code class="interfacename">DataSource</code> instances.
      For non-Spring, JTA-driven Hibernate transactions, you have to use the
      Hibernate JCA connector, or extra Hibernate transaction code with the
      <code class="interfacename">TransactionManagerLookup</code> configured for
      proper JVM-level caching.</p><p>Spring-driven transactions can work as well with a locally defined
      Hibernate <code class="interfacename">SessionFactory</code> as they do with
      a local JDBC <code class="interfacename">DataSource </code>if they are
      accessing a single database. Thus you only have to use Spring's JTA
      transaction strategy when you have distributed transaction requirements.
      A JCA connector requires container-specific deployment steps, and
      obviously JCA support in the first place. This configuration requires
      more work than deploying a simple web application with local resource
      definitions and Spring-driven transactions. Also, you often need the
      Enterprise Edition of your container if you are using, for example,
      WebLogic Express, which does not provide JCA. A Spring application with
      local resources and transactions spanning one single database works in
      any Java EE web container (without JTA, JCA, or EJB) such as Tomcat,
      Resin, or even plain Jetty. Additionally, you can easily reuse such a
      middle tier in desktop applications or test suites.</p><p>All things considered, if you do not use EJBs, stick with local
      <code class="interfacename">SessionFactory</code> setup and Spring's
      <code class="classname">HibernateTransactionManager</code> or
      <code class="classname">JtaTransactionManager</code>. You get all of the
      benefits, including proper transactional JVM-level caching and
      distributed transactions, without the inconvenience of container
      deployment. JNDI registration of a Hibernate
      <code class="interfacename">SessionFactory</code> through the JCA connector
      only adds value when used in conjunction with EJBs.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="orm-hibernate-invalid-jdbc-access-error"></a>13.3.7&nbsp;Spurious application server warnings with Hibernate</h3></div></div></div><p>In some JTA environments with very strict
      <code class="interfacename">XADataSource</code> implementations -- currently
      only some WebLogic Server and WebSphere versions -- when Hibernate is
      configured without regard to the JTA
      <code class="interfacename">PlatformTransactionManager</code> object for
      that environment, it is possible for spurious warning or exceptions to
      show up in the application server log. These warnings or exceptions
      indicate that the connection being accessed is no longer valid, or JDBC
      access is no longer valid, possibly because the transaction is no longer
      active. As an example, here is an actual exception from WebLogic:</p><pre class="programlisting">java.sql.SQLException: The transaction is no longer active - status: 'Committed'.
   No further JDBC access is allowed within this transaction.</pre><p>You resolve this warning by simply making Hibernate aware of the
      JTA <code class="interfacename">PlatformTransactionManager</code> instance,
      to which it will synchronize (along with Spring). You have two options
      for doing this:</p><div class="itemizedlist"><ul type="disc"><li><p>If in your application context you are already directly
          obtaining the JTA
          <code class="interfacename">PlatformTransactionManager</code> object
          (presumably from JNDI through
          <code class="literal">JndiObjectFactoryBean/<code class="literal">&lt;jee:jndi-lookup&gt;</code></code>)
          and feeding it, for example, to Spring's
          <code class="classname">JtaTransactionManager</code>, then the easiest way
          is to specify a reference to the bean defining this JTA
          <code class="interfacename">PlatformTransactionManager</code>
          instance as
          the value of the <span class="property">jtaTransactionManager</span> property
          for <code class="classname">LocalSessionFactoryBean.</code> Spring then makes
          the object available to Hibernate.</p></li><li><p>More likely you do not already have the JTA
          <code class="interfacename">PlatformTransactionManager</code> instance,
          because Spring's <code class="classname">JtaTransactionManager</code> can
          find it itself. Thus
          you need to configure Hibernate to look up JTA
          <code class="interfacename">PlatformTransactionManager</code> directly.
          You do this by configuring an application server- specific
          <code class="literal">TransactionManagerLookup</code> class in the Hibernate
          configuration, as described in the Hibernate manual.</p></li></ul></div><p>The remainder of this section describes the sequence of events
      that occur with and without Hibernate's awareness of the JTA
      <code class="interfacename">PlatformTransactionManager</code>.</p><p>When Hibernate is not configured with any awareness of the JTA
      <code class="interfacename">PlatformTransactionManager</code>, the following
      events occur when a JTA transaction commits:</p><div class="orderedlist"><ol type="1"><li><p>The JTA transaction commits.</p></li><li><p>Spring's <code class="classname">JtaTransactionManager</code> is
          synchronized to the JTA transaction, so it is called back through an
          <span class="emphasis"><em>afterCompletion</em></span> callback by the JTA transaction
          manager.</p></li><li><p>Among other activities, this synchronization can
          trigger a callback by Spring to Hibernate, through Hibernate's
          <code class="literal">afterTransactionCompletion</code> callback (used
          to clear the Hibernate cache), followed by an explicit
          <code class="literal">close()</code> call on the Hibernate Session, which
          causes Hibernate to attempt to <code class="literal">close()</code> the JDBC
          Connection.</p></li><li><p>In some environments, this
          <code class="methodname">Connection.close()</code> call then triggers the
          warning or error, as the application server no longer considers the
          <code class="interfacename">Connection</code> usable at all, because the
          transaction has already been committed.</p></li></ol></div><p>When Hibernate is configured with awareness of the JTA
      <code class="interfacename">PlatformTransactionManager</code>, the following
      events occur when a JTA transaction commits:</p><div class="orderedlist"><ol type="1"><li><p>the JTA transaction is ready to commit.</p></li><li><p>Spring's <code class="classname">JtaTransactionManager</code> is
          synchronized to the JTA transaction, so the transaction is called
          back through a <span class="emphasis"><em>beforeCompletion</em></span> callback by the
          JTA transaction manager.</p></li><li><p>Spring is aware that Hibernate itself is synchronized to the
          JTA transaction, and behaves differently than in the previous
          scenario. Assuming the Hibernate
          <code class="interfacename">Session</code> needs to be closed at all,
          Spring will close it now.</p></li><li><p>The JTA transaction commits.</p></li><li><p>Hibernate is synchronized to the JTA transaction, so the
          transaction is called back through an
          <span class="emphasis"><em>afterCompletion</em></span> callback by the JTA transaction
          manager, and can properly clear its cache.</p></li></ol></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="orm-jdo"></a>13.4&nbsp;JDO</h2></div></div></div><p>Spring supports the standard JDO 2.0 and 2.1 APIs as data access
    strategy, following the same style as the Hibernate support. The
    corresponding integration classes reside in the
    <code class="literal">org.springframework.orm.jdo</code> package.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="orm-jdo-setup"></a>13.4.1&nbsp;<code class="interfacename">PersistenceManagerFactory</code>
      setup</h3></div></div></div><p>Spring provides a
      <code class="classname">LocalPersistenceManagerFactoryBean</code> class that
      allows you to define a local JDO
      <code class="interfacename">PersistenceManagerFactory</code> within a Spring
      application context:</p><pre class="programlisting">&lt;<span class="hl-tag">beans</span>&gt;

  &lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"myPmf"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"org.springframework.orm.jdo.LocalPersistenceManagerFactoryBean"</span>&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"configLocation"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"classpath:kodo.properties"</span>/&gt;
  &lt;<span class="hl-tag">/bean</span>&gt;

&lt;<span class="hl-tag">/beans</span>&gt;</pre><p>Alternatively, you can set up a
      <code class="interfacename">PersistenceManagerFactory</code> through direct
      instantiation of a
      <code class="interfacename">PersistenceManagerFactory</code> implementation
      class. A JDO <code class="interfacename">PersistenceManagerFactory</code>
      implementation class follows the JavaBeans pattern, just like a JDBC
      <code class="interfacename">DataSource</code> implementation class, which is
      a natural fit for a configuration that uses Spring. This setup style
      usually supports a Spring-defined JDBC
      <code class="interfacename">DataSource</code>, passed into the
      <code class="classname">connectionFactory</code> property. For example, for the
      open source JDO implementation DataNucleus (formerly JPOX) (<a class="ulink" href="http://www.datanucleus.org/" target="_top">http://www.datanucleus.org/</a>),
      this is the XML configuration of the
      <code class="interfacename">PersistenceManagerFactory</code>
      implementation:</p><pre class="programlisting">&lt;<span class="hl-tag">beans</span>&gt;

 &lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"dataSource"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"org.apache.commons.dbcp.BasicDataSource"</span> <span class="hl-attribute">destroy-method</span>=<span class="hl-value">"close"</span>&gt;
   &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"driverClassName"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"${jdbc.driverClassName}"</span>/&gt;
   &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"url"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"${jdbc.url}"</span>/&gt;
   &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"username"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"${jdbc.username}"</span>/&gt;
   &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"password"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"${jdbc.password}"</span>/&gt;
 &lt;<span class="hl-tag">/bean</span>&gt;

 &lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"myPmf"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"org.datanucleus.jdo.JDOPersistenceManagerFactory"</span> <span class="hl-attribute">destroy-method</span>=<span class="hl-value">"close"</span>&gt;
   &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"connectionFactory"</span> <span class="hl-attribute">ref</span>=<span class="hl-value">"dataSource"</span>/&gt;
   &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"nontransactionalRead"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"true"</span>/&gt;
 &lt;<span class="hl-tag">/bean</span>&gt;

&lt;<span class="hl-tag">/beans</span>&gt;</pre><p>You can also set up JDO
      <code class="interfacename">PersistenceManagerFactory</code> in the JNDI
      environment of a Java EE application server, usually through the JCA
      connector provided by the particular JDO implementation. Spring's
      standard <code class="literal">JndiObjectFactoryBean /
      <code class="literal">&lt;jee:jndi-lookup&gt;</code></code> can be used to
      retrieve and expose such a
      <code class="interfacename">PersistenceManagerFactory</code>. However,
      outside an EJB context, no real benefit exists in holding the
      <code class="interfacename">PersistenceManagerFactory</code> in JNDI: only
      choose such a setup for a good reason. See <a class="xref" href="orm.html#orm-hibernate-resources" title="13.3.6&nbsp;Comparing container-managed and locally defined resources">Section&nbsp;13.3.6, &#8220;Comparing container-managed and locally defined resources&#8221;</a> for a discussion; the arguments
      there apply to JDO as well.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="orm-jdo-daos-straight"></a>13.4.2&nbsp;Implementing DAOs based on the plain JDO API</h3></div></div></div><p>DAOs can also be written directly against plain JDO API, without
      any Spring dependencies, by using an injected
      <code class="interfacename">PersistenceManagerFactory</code>. The following
      is an example of a corresponding DAO implementation:</p><pre class="programlisting"><span class="hl-keyword">public</span> <span class="hl-keyword">class</span> ProductDaoImpl <span class="hl-keyword">implements</span> ProductDao {

    <span class="hl-keyword">private</span> PersistenceManagerFactory persistenceManagerFactory;

    <span class="hl-keyword">public</span> <span class="hl-keyword">void</span> setPersistenceManagerFactory(PersistenceManagerFactory pmf) {
        <span class="hl-keyword">this</span>.persistenceManagerFactory = pmf;
    }

    <span class="hl-keyword">public</span> Collection loadProductsByCategory(String category) {
        PersistenceManager pm = <span class="hl-keyword">this</span>.persistenceManagerFactory.getPersistenceManager();
        <span class="hl-keyword">try</span> {
            Query query = pm.newQuery(Product.<span class="hl-keyword">class</span>, <span class="hl-string">"category = pCategory"</span>);
            query.declareParameters(<span class="hl-string">"String pCategory"</span>); 
            <span class="hl-keyword">return</span> query.execute(category);
        }
        <span class="hl-keyword">finally</span> {
          pm.close();
        }
    }
}</pre><p>Because the above DAO follows the dependency injection pattern, it
      fits nicely into a Spring container, just as it would if coded against
      Spring's <code class="classname">JdoTemplate</code>:</p><pre class="programlisting">&lt;<span class="hl-tag">beans</span>&gt;

  &lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"myProductDao"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"product.ProductDaoImpl"</span>&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"persistenceManagerFactory"</span> <span class="hl-attribute">ref</span>=<span class="hl-value">"myPmf"</span>/&gt;
  &lt;<span class="hl-tag">/bean</span>&gt;

&lt;<span class="hl-tag">/beans</span>&gt;</pre><p>The main problem with such DAOs is that they always get a new
      <code class="interfacename">PersistenceManager</code> from the factory. To
      access a Spring-managed transactional
      <code class="interfacename">PersistenceManager</code>, define a
      <code class="classname">TransactionAwarePersistenceManagerFactoryProxy</code>
      (as included in Spring) in front of your target
      <code class="interfacename">PersistenceManagerFactory</code>, then passing a
      reference to that proxy into your DAOs as in the following example:</p><pre class="programlisting">&lt;<span class="hl-tag">beans</span>&gt;

  &lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"myPmfProxy"</span>
      <span class="hl-attribute">class</span>=<span class="hl-value">"org.springframework.orm.jdo.TransactionAwarePersistenceManagerFactoryProxy"</span>&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"targetPersistenceManagerFactory"</span> <span class="hl-attribute">ref</span>=<span class="hl-value">"myPmf"</span>/&gt;
  &lt;<span class="hl-tag">/bean</span>&gt;

  &lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"myProductDao"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"product.ProductDaoImpl"</span>&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"persistenceManagerFactory"</span> <span class="hl-attribute">ref</span>=<span class="hl-value">"myPmfProxy"</span>/&gt;
  &lt;<span class="hl-tag">/bean</span>&gt;

&lt;<span class="hl-tag">/beans</span>&gt;</pre><p>Your data access code will receive a transactional
      <code class="interfacename">PersistenceManager</code> (if any) from the
      <code class="methodname">PersistenceManagerFactory.getPersistenceManager()</code>
      method that it calls. The latter method call goes through the proxy,
      which first checks for a current transactional
      <code class="interfacename">PersistenceManager</code> before getting a new
      one from the factory. Any <code class="methodname">close()</code> calls on the
      <code class="interfacename">PersistenceManager</code> are ignored in case of
      a transactional
      <code class="interfacename">PersistenceManager</code>.</p><p>If your data access code always runs within an active transaction
      (or at least within active transaction synchronization), it is safe to
      omit the <code class="methodname">PersistenceManager.close()</code> call and
      thus the entire <code class="literal">finally</code> block, which you might do to
      keep your DAO implementations concise:</p><pre class="programlisting"><span class="hl-keyword">public</span> <span class="hl-keyword">class</span> ProductDaoImpl <span class="hl-keyword">implements</span> ProductDao {

    <span class="hl-keyword">private</span> PersistenceManagerFactory persistenceManagerFactory;

    <span class="hl-keyword">public</span> <span class="hl-keyword">void</span> setPersistenceManagerFactory(PersistenceManagerFactory pmf) {
        <span class="hl-keyword">this</span>.persistenceManagerFactory = pmf;
    }

    <span class="hl-keyword">public</span> Collection loadProductsByCategory(String category) {
        PersistenceManager pm = <span class="hl-keyword">this</span>.persistenceManagerFactory.getPersistenceManager();
        Query query = pm.newQuery(Product.<span class="hl-keyword">class</span>, <span class="hl-string">"category = pCategory"</span>);
        query.declareParameters(<span class="hl-string">"String pCategory"</span>); 
        <span class="hl-keyword">return</span> query.execute(category);
    }
}</pre><p>With such DAOs that rely on active transactions, it is recommended
      that you enforce active transactions through turning off
      <code class="classname">TransactionAwarePersistenceManagerFactoryProxy</code>'s
      <code class="classname">allowCreate</code> flag:</p><pre class="programlisting">&lt;<span class="hl-tag">beans</span>&gt;

  &lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"myPmfProxy"</span>
      <span class="hl-attribute">class</span>=<span class="hl-value">"org.springframework.orm.jdo.TransactionAwarePersistenceManagerFactoryProxy"</span>&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"targetPersistenceManagerFactory"</span> <span class="hl-attribute">ref</span>=<span class="hl-value">"myPmf"</span>/&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"allowCreate"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"false"</span>/&gt;
  &lt;<span class="hl-tag">/bean</span>&gt;

  &lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"myProductDao"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"product.ProductDaoImpl"</span>&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"persistenceManagerFactory"</span> <span class="hl-attribute">ref</span>=<span class="hl-value">"myPmfProxy"</span>/&gt;
  &lt;<span class="hl-tag">/bean</span>&gt;

&lt;<span class="hl-tag">/beans</span>&gt;</pre><p>The main advantage of this DAO style is that it depends on JDO API
      only; no import of any Spring class is required. This is of course
      appealing from a non-invasiveness perspective, and might feel more
      natural to JDO developers.</p><p>However, the DAO throws plain
      <code class="exceptionname">JDOException</code> (which is unchecked, so does
      not have to be declared or caught), which means that callers can only
      treat exceptions as fatal, unless you want to depend on JDO's own
      exception structure. Catching specific causes such as an optimistic
      locking failure is not possible without tying the caller to the
      implementation strategy. This trade off might be acceptable to
      applications that are strongly JDO-based and/or do not need any special
      exception treatment.</p><p>In summary, you can DAOs based on the plain JDO API, and they can
      still participate in Spring-managed transactions. This strategy might
      appeal to you if you are already familiar with JDO. However, such DAOs
      throw plain <code class="exceptionname">JDOException</code>, and you would
      have to convert explicitly to Spring's
      <code class="exceptionname">DataAccessException</code> (if desired).</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="orm-jdo-tx"></a>13.4.3&nbsp;Transaction management</h3></div></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.gif"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>You are <span class="emphasis"><em>strongly</em></span> encouraged to read <a class="xref" href="transaction.html#transaction-declarative" title="10.5&nbsp;Declarative transaction management">Section&nbsp;10.5, &#8220;Declarative transaction management&#8221;</a> if you have not done so, to get a
        more detailed coverage of Spring's declarative transaction
        support.</p></td></tr></table></div><p>To execute service operations within transactions, you can use
      Spring's common declarative transaction facilities. For example:</p><pre class="programlisting">&lt;<span class="hl-tag">?xml version="1.0" encoding="UTF-8"?</span>&gt;
&lt;<span class="hl-tag">beans</span>
        <span class="hl-attribute">xmlns</span>=<span class="hl-value">"http://www.springframework.org/schema/beans"</span>
        <span class="hl-attribute">xmlns:xsi</span>=<span class="hl-value">"http://www.w3.org/2001/XMLSchema-instance"</span>
        <span class="hl-attribute">xmlns:aop</span>=<span class="hl-value">"http://www.springframework.org/schema/aop"</span>
        <span class="hl-attribute">xmlns:tx</span>=<span class="hl-value">"http://www.springframework.org/schema/tx"</span>
        <span class="hl-attribute">xsi:schemaLocation</span>=<span class="hl-value">"
   http://www.springframework.org/schema/beans 
   http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
   http://www.springframework.org/schema/tx 
   http://www.springframework.org/schema/tx/spring-tx-3.0.xsd
   http://www.springframework.org/schema/aop 
   http://www.springframework.org/schema/aop/spring-aop-3.0.xsd"</span>&gt;

  &lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"myTxManager"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"org.springframework.orm.jdo.JdoTransactionManager"</span>&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"persistenceManagerFactory"</span> <span class="hl-attribute">ref</span>=<span class="hl-value">"myPmf"</span>/&gt;
  &lt;<span class="hl-tag">/bean</span>&gt;

  &lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"myProductService"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"product.ProductServiceImpl"</span>&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"productDao"</span> <span class="hl-attribute">ref</span>=<span class="hl-value">"myProductDao"</span>/&gt;
  &lt;<span class="hl-tag">/bean</span>&gt;

  &lt;<span class="hl-tag">tx:advice</span> <span class="hl-attribute">id</span>=<span class="hl-value">"txAdvice"</span> <span class="hl-attribute">transaction-manager</span>=<span class="hl-value">"txManager"</span>&gt;
    &lt;<span class="hl-tag">tx:attributes</span>&gt;
      &lt;<span class="hl-tag">tx:method</span> <span class="hl-attribute">name</span>=<span class="hl-value">"increasePrice*"</span> <span class="hl-attribute">propagation</span>=<span class="hl-value">"REQUIRED"</span>/&gt;
      &lt;<span class="hl-tag">tx:method</span> <span class="hl-attribute">name</span>=<span class="hl-value">"someOtherBusinessMethod"</span> <span class="hl-attribute">propagation</span>=<span class="hl-value">"REQUIRES_NEW"</span>/&gt;
      &lt;<span class="hl-tag">tx:method</span> <span class="hl-attribute">name</span>=<span class="hl-value">"*"</span> <span class="hl-attribute">propagation</span>=<span class="hl-value">"SUPPORTS"</span> <span class="hl-attribute">read-only</span>=<span class="hl-value">"true"</span>/&gt;
    &lt;<span class="hl-tag">/tx:attributes</span>&gt;
  &lt;<span class="hl-tag">/tx:advice</span>&gt;

  &lt;<span class="hl-tag">aop:config</span>&gt;
    &lt;<span class="hl-tag">aop:pointcut</span> <span class="hl-attribute">id</span>=<span class="hl-value">"productServiceMethods"</span>
            <span class="hl-attribute">expression</span>=<span class="hl-value">"execution(* product.ProductService.*(..))"</span>/&gt;
    &lt;<span class="hl-tag">aop:advisor</span> <span class="hl-attribute">advice-ref</span>=<span class="hl-value">"txAdvice"</span> <span class="hl-attribute">pointcut-ref</span>=<span class="hl-value">"productServiceMethods"</span>/&gt;
  &lt;<span class="hl-tag">/aop:config</span>&gt;

&lt;<span class="hl-tag">/beans</span>&gt;</pre><p>JDO requires an active transaction to modify a persistent object.
      The non-transactional flush concept does not exist in JDO, in contrast
      to Hibernate. For this reason, you need to set up the chosen JDO
      implementation for a specific environment. Specifically, you need to set
      it up explicitly for JTA synchronization, to detect an active JTA
      transaction itself. This is not necessary for local transactions as
      performed by Spring's <code class="classname">JdoTransactionManager</code>, but
      it is necessary to participate in JTA transactions, whether driven by
      Spring's <code class="classname">JtaTransactionManager</code> or by EJB CMT and
      plain JTA.</p><p><code class="classname">JdoTransactionManager</code> is capable of
      exposing a JDO transaction to JDBC access code that accesses the same
      JDBC <code class="interfacename">DataSource</code>, provided that the
      registered <code class="classname">JdoDialect</code> supports retrieval of the
      underlying JDBC <code class="interfacename">Connection</code>. This is the
      case for JDBC-based JDO 2.0 implementations by default.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="orm-jdo-dialect"></a>13.4.4&nbsp;<code class="interfacename">JdoDialect</code></h3></div></div></div><p>As an advanced feature, both <code class="classname">JdoTemplate</code>
      and <code class="classname">JdoTransactionManager</code> support a custom
      <code class="interfacename">JdoDialect</code> that can be passed into the
      <code class="code">jdoDialect</code> bean property. In this scenario, the DAOs will
      not receive a <code class="interfacename">PersistenceManagerFactory</code>
      reference but rather a full <code class="classname">JdoTemplate</code> instance
      (for example, passed into the <code class="literal">jdoTemplate</code>
      property of <code class="classname">JdoDaoSupport</code>). Using a
      <code class="interfacename">JdoDialect</code> implementation, you can enable
      advanced features supported by Spring, usually in a vendor-specific
      manner:</p><div class="itemizedlist"><ul type="disc"><li><p>Applying specific transaction semantics such as custom
          isolation level or transaction timeout</p></li><li><p>Retrieving the transactional JDBC
          <code class="interfacename">Connection</code> for exposure to JDBC-based
          DAOs</p></li><li><p>Applying query timeouts, which are automatically calculated
          from Spring-managed transaction timeouts</p></li><li><p>Eagerly flushing a
          <code class="interfacename">PersistenceManager,</code> to make
          transactional changes visible to JDBC-based data access code</p></li><li><p>Advanced translation of <code class="literal">JDOExceptions</code> to
          Spring <code class="literal">DataAccessExceptions</code></p></li></ul></div><p>See the <code class="classname">JdoDialect</code> Javadoc for more details
      on its operations and how to use them within Spring's JDO
      support.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="orm-jpa"></a>13.5&nbsp;JPA</h2></div></div></div><p>The Spring JPA, available under the
    <code class="literal">org.springframework.orm.jpa</code> package, offers
    comprehensive support for the <a class="ulink" href="http://java.sun.com/developer/technicalArticles/J2EE/jpa/index.html" target="_top">Java
    Persistence API</a> in a similar manner to the integration with
    Hibernate or JDO, while being aware of the underlying implementation in
    order to provide additional features.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="orm-jpa-setup"></a>13.5.1&nbsp;Three options for JPA setup in a Spring environment</h3></div></div></div><p>The Spring JPA support offers three ways of setting up the JPA
      <code class="interfacename">EntityManagerFactory</code> that will be used by
      the application to obtain an entity manager.</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="orm-jpa-setup-lemfb"></a>13.5.1.1&nbsp;<code class="classname">LocalEntityManagerFactoryBean</code></h4></div></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.gif"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Only use this option in simple deployment environments such as
          stand-alone applications and integration tests.</p></td></tr></table></div><p>The <code class="classname">LocalEntityManagerFactoryBean</code> creates
        an <code class="interfacename">EntityManagerFactory</code> suitable for
        simple deployment environments where the application uses only JPA for
        data access. The factory bean uses the JPA
        <code class="interfacename">PersistenceProvider</code> autodetection
        mechanism (according to JPA's Java SE bootstrapping) and, in most
        cases, requires you to specify only the persistence unit name:</p><pre class="programlisting">&lt;<span class="hl-tag">beans</span>&gt;

   &lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"myEmf"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"org.springframework.orm.jpa.LocalEntityManagerFactoryBean"</span>&gt;
      &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"persistenceUnitName"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"myPersistenceUnit"</span>/&gt;
   &lt;<span class="hl-tag">/bean</span>&gt;

&lt;<span class="hl-tag">/beans</span>&gt;</pre><p>This form of JPA deployment is the simplest and the most
        limited. You cannot refer to
        an existing JDBC <code class="interfacename">DataSource</code> bean
        definition and no support for global transactions exists. Furthermore,
        weaving (byte-code transformation) of persistent classes is
        provider-specific, often requiring a specific JVM agent to specified
        on startup. This option is sufficient only for stand-alone
        applications and test environments, for which the JPA specification is
        designed.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="orm-jpa-setup-jndi"></a>13.5.1.2&nbsp;Obtaining an <code class="classname">EntityManagerFactory</code> from
        JNDI</h4></div></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.gif"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Use this option when deploying to a Java EE 5 server. Check
          your server's documentation on how to deploy a custom JPA provider
          into your server, allowing for a different provider than the
          server's default.</p></td></tr></table></div><p>Obtaining an <code class="interfacename">EntityManagerFactory</code>
        from JNDI (for example in a Java EE 5 environment), is simply a matter
        of changing the XML configuration:</p><pre class="programlisting">&lt;<span class="hl-tag">beans</span>&gt;

    &lt;<span class="hl-tag">jee:jndi-lookup</span> <span class="hl-attribute">id</span>=<span class="hl-value">"myEmf"</span> <span class="hl-attribute">jndi-name</span>=<span class="hl-value">"persistence/myPersistenceUnit"</span>/&gt;

&lt;<span class="hl-tag">/beans</span>&gt;</pre><p>This action assumes standard Java EE 5 bootstrapping: the Java
        EE server autodetects persistence units (in effect,
        <code class="literal">META-INF/persistence.xml</code> files in application jars)
        and <code class="literal">persistence-unit-ref</code> entries in the Java EE
        deployment descriptor (for example, <code class="literal">web.xml</code>) and
        defines environment naming context locations for those persistence
        units.</p><p>In such a scenario, the entire persistence unit deployment,
        including the weaving (byte-code transformation) of persistent
        classes, is up to the Java EE server. The JDBC
        <code class="interfacename">DataSource</code> is defined through a JNDI
        location in the <code class="literal">META-INF/persistence.xml</code> file;
        EntityManager transactions are integrated with the server's JTA
        subsystem. Spring merely uses the obtained
        <code class="interfacename">EntityManagerFactory</code>, passing it on to
        application objects through dependency injection, and managing
        transactions for the persistence unit,
        typically through <code class="classname">JtaTransactionManager</code>.</p><p>If multiple persistence units are used in the same application,
        the bean names of such JNDI-retrieved persistence units should match
        the persistence unit names that the application uses to refer to them,
        for example, in <code class="literal">@PersistenceUnit</code> and
        <code class="literal">@PersistenceContext</code> annotations.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="orm-jpa-setup-lcemfb"></a>13.5.1.3&nbsp;<code class="classname">LocalContainerEntityManagerFactoryBean</code></h4></div></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.gif"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Use this option for full JPA capabilities in a Spring-based
          application environment. This includes web containers such as Tomcat
          as well as stand-alone applications and integration tests with
          sophisticated persistence requirements.</p></td></tr></table></div><p>The
        <code class="classname">LocalContainerEntityManagerFactoryBean</code> gives
        full control over <code class="interfacename">EntityManagerFactory</code>
        configuration and is appropriate for environments where fine-grained
        customization is required. The
        <code class="classname">LocalContainerEntityManagerFactoryBean</code> creates
        a <code class="interfacename">PersistenceUnitInfo</code> instance based
        on the <code class="literal">persistence.xml</code> file, the supplied
        <code class="literal">dataSourceLookup</code> strategy, and the specified
        <code class="literal">loadTimeWeaver</code>. It is thus possible to work with
        custom data sources outside of JNDI and to control the weaving
        process. The following example shows a typical bean definition for a
        <code class="interfacename">LocalContainerEntityManagerFactoryBean</code>:</p><pre class="programlisting">&lt;<span class="hl-tag">beans</span>&gt;
        
 &lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"myEmf"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean"</span>&gt;
  &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"dataSource"</span> <span class="hl-attribute">ref</span>=<span class="hl-value">"someDataSource"</span>/&gt;
  &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"loadTimeWeaver"</span>&gt;
    &lt;<span class="hl-tag">bean</span> <span class="hl-attribute">class</span>=<span class="hl-value">"org.springframework.instrument.classloading.InstrumentationLoadTimeWeaver"</span>/&gt;
  &lt;<span class="hl-tag">/property</span>&gt;
 &lt;<span class="hl-tag">/bean</span>&gt;
 
&lt;<span class="hl-tag">/beans</span>&gt;</pre><p>The following example shows a typical
        <code class="literal">persistence.xml</code> file:</p><pre class="programlisting">&lt;<span class="hl-tag">persistence</span> <span class="hl-attribute">xmlns</span>=<span class="hl-value">"http://java.sun.com/xml/ns/persistence"</span> <span class="hl-attribute">version</span>=<span class="hl-value">"1.0"</span>&gt;

  &lt;<span class="hl-tag">persistence-unit</span> <span class="hl-attribute">name</span>=<span class="hl-value">"myUnit"</span> <span class="hl-attribute">transaction-type</span>=<span class="hl-value">"RESOURCE_LOCAL"</span>&gt;
    &lt;<span class="hl-tag">mapping-file</span>&gt;META-INF/orm.xml&lt;<span class="hl-tag">/mapping-file</span>&gt;
    &lt;<span class="hl-tag">exclude-unlisted-classes</span>/&gt;
  &lt;<span class="hl-tag">/persistence-unit</span>&gt;

&lt;<span class="hl-tag">/persistence</span>&gt;</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.gif"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>The <code class="code">exclude-unlisted-classes</code> element always
          indicates that <span class="emphasis"><em>no</em></span> scanning for annotated entity
          classes is supposed to occur, in order to support the
          <code class="code">&lt;exclude-unlisted-classes/&gt;</code> shortcut. This is in
          line with the JPA specification, which suggests that shortcut, but
          unfortunately is in conflict with the JPA XSD, which implies
          <code class="code">false</code> for that shortcut. Consequently,
          <code class="code">&lt;exclude-unlisted-classes&gt; false
          &lt;/exclude-unlisted-classes/&gt;</code> is not supported. Simply
          omit the <code class="code">exclude-unlisted-classes</code> element if you want
          entity class scanning to occur.</p></td></tr></table></div><p>Using the
        <code class="classname">LocalContainerEntityManagerFactoryBean</code> is the
        most powerful JPA setup option, allowing for flexible local
        configuration within the application. It supports links to an existing
        JDBC <code class="interfacename">DataSource</code>, supports both local
        and global transactions, and so on. However, it also imposes
        requirements on the runtime environment, such as the availability of
        a weaving-capable class loader if the persistence provider demands
        byte-code transformation.</p><p>This option may conflict with the built-in JPA capabilities of a
        Java EE 5 server. In a full Java EE 5 environment, consider obtaining
        your <code class="interfacename">EntityManagerFactory</code> from JNDI.
        Alternatively, specify a custom
        <code class="classname">persistenceXmlLocation</code> on your
        <code class="classname">LocalContainerEntityManagerFactoryBean</code>
        definition, for example, META-INF/my-persistence.xml, and only include
        a descriptor with that name in your application jar files. Because the
        Java EE 5 server only looks for default
        <code class="literal">META-INF/persistence.xml</code> files, it ignores such
        custom persistence units and hence avoid conflicts with a
        Spring-driven JPA setup upfront. (This applies to Resin 3.1, for
        example.)</p><div class="sidebar"><p class="title"><b>When is load-time weaving required?</b></p><p>Not all JPA providers require a JVM agent ; Hibernate is an
          example of one that does not. If your provider does not require an
          agent or you have other alternatives, such as applying enhancements
          at build time through a custom compiler or an ant task, the
          load-time weaver <span class="bold"><strong>should not</strong></span> be
          used.</p></div><p>The <code class="interfacename">LoadTimeWeaver</code> interface is a
        Spring-provided class that allows JPA
        <code class="interfacename">ClassTransformer</code> instances to be
        plugged in a specific manner, depending whether the environment is a
        web container or application server. 
        Hooking <code class="literal">ClassTransformers</code> through a Java 5 <a class="ulink" href="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/instrument/package-summary.html" target="_top">agent</a>
        typically is not efficient. The agents work against the
        <span class="emphasis"><em>entire virtual machine</em></span> and inspect
        <span class="emphasis"><em>every</em></span> class that is loaded, which is usually
        undesirable in a production server environment.</p><p>Spring provides a number of
        <code class="interfacename">LoadTimeWeaver</code> implementations for
        various environments, allowing
        <code class="interfacename">ClassTransformer</code> instances to be
        applied only <span class="emphasis"><em>per class loader</em></span> and not per
        VM.</p><p>Refer to <a class="xref" href="aop.html#aop-aj-ltw-spring" title="7.8.4.5&nbsp;Spring configuration">Section&nbsp;7.8.4.5, &#8220;Spring configuration&#8221;</a> in the AOP chapter for more insight regarding the 
        <code class="interfacename">LoadTimeWeaver</code> implementations and their setup, either generic or customized to 
        various platforms (such as Tomcat, WebLogic, OC4J, GlassFish, Resin and JBoss).</p><p>As described in the aforementioned section, you can configure a context-wide <code class="interfacename">LoadTimeWeaver</code>
		using the  <code class="literal">context:load-time-weaver</code> configuration element. (This has been available since Spring 2.5.)
		Such a global weaver is picked up by all JPA <code class="classname">LocalContainerEntityManagerFactoryBeans</code>
        automatically. This is the preferred way of setting up a load-time weaver, delivering autodetection of the platform 
        (WebLogic, OC4J, GlassFish, Tomcat, Resin, JBoss or VM agent) and automatic propagation of the weaver to all weaver-aware beans:</p><pre class="programlisting">&lt;<span class="hl-tag">context:load-time-weaver</span>/&gt;
&lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"emf"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean"</span>&gt;
    ...
&lt;<span class="hl-tag">/bean</span>&gt;</pre><p> However, if needed, one can manually specify a dedicated weaver through the <code class="literal">loadTimeWeaver</code> property:</p><pre class="programlisting">&lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"emf"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean"</span>&gt;
  &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"loadTimeWeaver"</span>&gt;
    &lt;<span class="hl-tag">bean</span> <span class="hl-attribute">class</span>=<span class="hl-value">"org.springframework.instrument.classloading.ReflectiveLoadTimeWeaver"</span>/&gt;
  &lt;<span class="hl-tag">/property</span>&gt;
&lt;<span class="hl-tag">/bean</span>&gt;</pre><p>No matter how the LTW is configured, using this technique, JPA applications relying on
          instrumentation can run in the target platform (ex: Tomcat) without needing an agent. 
          This is important especially when the hosting applications rely on different JPA implementations 
          because the JPA transformers are applied only at class loader level and thus are
          isolated from each other.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="orm-jpa-multiple-pu"></a>13.5.1.4&nbsp;Dealing with multiple persistence units</h4></div></div></div><p>For applications that rely on multiple persistence units
        locations, stored in various JARS in the classpath, for example,
        Spring offers the
        <code class="interfacename">PersistenceUnitManager</code> to act as a
        central repository and to avoid the persistence units discovery
        process, which can be expensive. The default implementation allows
        multiple locations to be specified that are parsed and later retrieved
        through the persistence unit name. (By default, the classpath is
        searched for <code class="filename">META-INF/persistence.xml</code>
        files.)</p><pre class="programlisting">&lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"pum"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"org.springframework.orm.jpa.persistenceunit.DefaultPersistenceUnitManager"</span>&gt;
  &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"persistenceXmlLocations"</span>&gt;
    &lt;<span class="hl-tag">list</span>&gt;
     &lt;<span class="hl-tag">value</span>&gt;org/springframework/orm/jpa/domain/persistence-multi.xml&lt;<span class="hl-tag">/value</span>&gt;
     &lt;<span class="hl-tag">value</span>&gt;classpath:/my/package/**/custom-persistence.xml&lt;<span class="hl-tag">/value</span>&gt;
     &lt;<span class="hl-tag">value</span>&gt;classpath*:META-INF/persistence.xml&lt;<span class="hl-tag">/value</span>&gt;
    &lt;<span class="hl-tag">/list</span>&gt;
  &lt;<span class="hl-tag">/property</span>&gt;
  &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"dataSources"</span>&gt;
   &lt;<span class="hl-tag">map</span>&gt;
    &lt;<span class="hl-tag">entry</span> <span class="hl-attribute">key</span>=<span class="hl-value">"localDataSource"</span> <span class="hl-attribute">value-ref</span>=<span class="hl-value">"local-db"</span>/&gt;
    &lt;<span class="hl-tag">entry</span> <span class="hl-attribute">key</span>=<span class="hl-value">"remoteDataSource"</span> <span class="hl-attribute">value-ref</span>=<span class="hl-value">"remote-db"</span>/&gt;
   &lt;<span class="hl-tag">/map</span>&gt;
  &lt;<span class="hl-tag">/property</span>&gt;
  &lt;<span class="hl-comment">!-- if no datasource is specified, use this one --</span>&gt;
  &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"defaultDataSource"</span> <span class="hl-attribute">ref</span>=<span class="hl-value">"remoteDataSource"</span>/&gt;
&lt;<span class="hl-tag">/bean</span>&gt;

&lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"emf"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean"</span>&gt;
  &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"persistenceUnitManager"</span> <span class="hl-attribute">ref</span>=<span class="hl-value">"pum"</span>/&gt;
  &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"persistenceUnitName"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"myCustomUnit"</span>/&gt;
&lt;<span class="hl-tag">/bean</span>&gt;</pre><p>The default implementation allows customization of the
        <code class="interfacename">PersistenceUnitInfo</code> instances,
        before they are fed to the JPA provider, declaratively through its
        properties,
        which affect <span class="emphasis"><em>all</em></span> hosted units, or
        programmatically, through the
        <code class="interfacename">PersistenceUnitPostProcessor</code>, which
        allows persistence unit selection. If no
        <code class="interfacename">PersistenceUnitManager</code> is specified,
        one is created and used internally by
        <code class="classname">LocalContainerEntityManagerFactoryBean</code>.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="orm-jpa-straight"></a>13.5.2&nbsp;Implementing DAOs based on plain JPA</h3></div></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.gif"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Although <code class="interfacename">EntityManagerFactory</code>
        instances are thread-safe,
        <code class="interfacename">EntityManager</code> instances are not. The
        injected JPA <code class="interfacename">EntityManager</code> behaves like
        an <code class="interfacename">EntityManager</code> fetched from an
        application server's JNDI environment, as defined by the JPA
        specification. It delegates all calls to the current transactional
        <code class="interfacename">EntityManager</code>, if any; otherwise, it
        falls back to a newly created
        <code class="interfacename">EntityManager</code> per operation, in effect
        making its usage thread-safe.</p></td></tr></table></div><p>It is possible to write code against the plain JPA without any
      Spring dependencies, by using an injected
      <code class="interfacename">EntityManagerFactory</code> or
      <code class="interfacename">EntityManager</code>. Spring can understand
      <code class="interfacename">@PersistenceUnit</code> and
      <code class="interfacename">@PersistenceContext</code> annotations both at
      field and method level if a
      <code class="classname">PersistenceAnnotationBeanPostProcessor</code> is
      enabled. A plain JPA DAO implementation using the
      <code class="interfacename">@PersistenceUnit</code> annotation might
      look like this:</p><pre class="programlisting"><span class="hl-keyword">public</span> <span class="hl-keyword">class</span> ProductDaoImpl <span class="hl-keyword">implements</span> ProductDao {

    <span class="hl-keyword">private</span> EntityManagerFactory emf;

    @PersistenceUnit
    <span class="hl-keyword">public</span> <span class="hl-keyword">void</span> setEntityManagerFactory(EntityManagerFactory emf) {
        <span class="hl-keyword">this</span>.emf = emf;
    }

    <span class="hl-keyword">public</span> Collection loadProductsByCategory(String category) {
        EntityManager em = <span class="hl-keyword">this</span>.emf.createEntityManager();
        <span class="hl-keyword">try</span> {
             Query query = em.createQuery(<span class="hl-string">"from Product as p where p.category = ?1"</span>);
             query.setParameter(1, category);
             <span class="hl-keyword">return</span> query.getResultList();
        }
        <span class="hl-keyword">finally</span> {
            <span class="hl-keyword">if</span> (em != null) {
                em.close();
            }
        }
    }
}</pre><p>The DAO above has no dependency on Spring and still fits nicely
      into a Spring application context. Moreover, the DAO takes advantage of
      annotations to require the injection of the default
      <code class="interfacename">EntityManagerFactory</code>:</p><pre class="programlisting">&lt;<span class="hl-tag">beans</span>&gt;

  &lt;<span class="hl-comment">!-- bean post-processor for JPA annotations --</span>&gt;
  &lt;<span class="hl-tag">bean</span> <span class="hl-attribute">class</span>=<span class="hl-value">"org.springframework.orm.jpa.support.PersistenceAnnotationBeanPostProcessor"</span>/&gt;

  &lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"myProductDao"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"product.ProductDaoImpl"</span>/&gt;

&lt;<span class="hl-tag">/beans</span>&gt;</pre><p>As an alternative to defining a
      <code class="classname">PersistenceAnnotationBeanPostProcessor</code>
      explicitly, consider using the Spring
      <code class="literal">context:annotation-config</code> XML element in your
      application context configuration. Doing so automatically registers all
      Spring standard post-processors for annotation-based configuration,
      including <code class="classname">CommonAnnotationBeanPostProcessor</code> and
      so on.</p><pre class="programlisting">&lt;<span class="hl-tag">beans</span>&gt;

  &lt;<span class="hl-comment">!-- post-processors for all standard config annotations --</span>&gt;
  &lt;<span class="hl-tag">context:annotation-config</span>/&gt;

  &lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"myProductDao"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"product.ProductDaoImpl"</span>/&gt;

&lt;<span class="hl-tag">/beans</span>&gt;</pre><p>The main problem with such a DAO is that it always creates a new
      <code class="interfacename">EntityManager</code> through the factory. You
      can avoid this by requesting a transactional
      <code class="interfacename">EntityManager</code> (also called "shared
      EntityManager" because it is a shared, thread-safe proxy for the actual
      transactional EntityManager) to be injected instead of the
      factory:</p><pre class="programlisting"><span class="hl-keyword">public</span> <span class="hl-keyword">class</span> ProductDaoImpl <span class="hl-keyword">implements</span> ProductDao {

    @PersistenceContext
    <span class="hl-keyword">private</span> EntityManager em;

    <span class="hl-keyword">public</span> Collection loadProductsByCategory(String category) {
       Query query = em.createQuery(<span class="hl-string">"from Product as p where p.category = :category"</span>);
       query.setParameter(<span class="hl-string">"category"</span>, category);
       <span class="hl-keyword">return</span> query.getResultList(); 
    }
}</pre><p>The <code class="literal">@PersistenceContext</code> annotation has an
      optional attribute <code class="literal">type</code>, which defaults to
      <code class="literal">PersistenceContextType.TRANSACTION</code>. This default is
      what you need to receive a shared EntityManager proxy. The alternative,
      <code class="literal">PersistenceContextType.EXTENDED</code>, is a completely
      different affair: This results in a so-called extended EntityManager,
      which is <span class="emphasis"><em>not thread-safe</em></span> and hence must not be used
      in a concurrently accessed component such as a Spring-managed singleton
      bean. Extended EntityManagers are only supposed to be used in stateful
      components that, for example, reside in a session, with the lifecycle of
      the EntityManager not tied to a current transaction but rather being
      completely up to the application.</p><div class="sidebar"><p class="title"><b>Method- and field-level Injection</b></p><p>Annotations that indicate dependency injections (such as
        <code class="literal">@PersistenceUnit</code> and
        <code class="literal">@PersistenceContext</code>) can be applied on field or
        methods inside a class, hence the expressions <span class="emphasis"><em>method-level
        injection</em></span> and <span class="emphasis"><em>field-level injection</em></span>.
        Field-level annotations are concise and easier to use while
        method-level allows for further processing of the injected dependency.
        In both cases the member visibility (public, protected, private) does
        not matter.</p><p>What about class-level annotations?</p><p>On the Java EE 5 platform, they are used for dependency
        declaration and not for resource injection.</p></div><p>The injected <code class="interfacename">EntityManager</code> is
      Spring-managed (aware of the ongoing transaction). It is important to
      note that even though the new DAO implementation uses method level
      injection of an <code class="interfacename">EntityManager</code> instead of
      an <code class="interfacename">EntityManagerFactory</code>, no change is
      required in the application context XML due to annotation usage.</p><p>The main advantage of this DAO style is that it only depends on
      Java Persistence API; no import of any Spring class is required.
      Moreover, as the JPA annotations are understood, the injections are
      applied automatically by the Spring container. This is appealing from a
      non-invasiveness perspective, and might feel more natural to JPA
      developers.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="orm-jpa-tx"></a>13.5.3&nbsp;Transaction Management</h3></div></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.gif"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>You are <span class="emphasis"><em>strongly</em></span> encouraged to read <a class="xref" href="transaction.html#transaction-declarative" title="10.5&nbsp;Declarative transaction management">Section&nbsp;10.5, &#8220;Declarative transaction management&#8221;</a> if you have not done so, to get a
        more detailed coverage of Spring's declarative transaction
        support.</p></td></tr></table></div><p>To execute service operations within transactions, you can use
      Spring's common declarative transaction facilities. For example:</p><pre class="programlisting">&lt;<span class="hl-tag">?xml version="1.0" encoding="UTF-8"?</span>&gt;
&lt;<span class="hl-tag">beans</span> <span class="hl-attribute">xmlns</span>=<span class="hl-value">"http://www.springframework.org/schema/beans"</span>
       <span class="hl-attribute">xmlns:xsi</span>=<span class="hl-value">"http://www.w3.org/2001/XMLSchema-instance"</span>
       <span class="hl-attribute">xmlns:aop</span>=<span class="hl-value">"http://www.springframework.org/schema/aop"</span>
       <span class="hl-attribute">xmlns:tx</span>=<span class="hl-value">"http://www.springframework.org/schema/tx"</span>
       <span class="hl-attribute">xsi:schemaLocation</span>=<span class="hl-value">"
       http://www.springframework.org/schema/beans 
       http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
       http://www.springframework.org/schema/tx 
       http://www.springframework.org/schema/tx/spring-tx-3.0.xsd
       http://www.springframework.org/schema/aop 
       http://www.springframework.org/schema/aop/spring-aop-3.0.xsd"</span>&gt;

  &lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"myTxManager"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"org.springframework.orm.jpa.JpaTransactionManager"</span>&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"entityManagerFactory"</span> <span class="hl-attribute">ref</span>=<span class="hl-value">"myEmf"</span>/&gt;
  &lt;<span class="hl-tag">/bean</span>&gt;

  &lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"myProductService"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"product.ProductServiceImpl"</span>&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"productDao"</span> <span class="hl-attribute">ref</span>=<span class="hl-value">"myProductDao"</span>/&gt;
  &lt;<span class="hl-tag">/bean</span>&gt;
  
  &lt;<span class="hl-tag">aop:config</span>&gt;
    &lt;<span class="hl-tag">aop:pointcut</span> <span class="hl-attribute">id</span>=<span class="hl-value">"productServiceMethods"</span> <span class="hl-attribute">expression</span>=<span class="hl-value">"execution(* product.ProductService.*(..))"</span>/&gt;
    &lt;<span class="hl-tag">aop:advisor</span> <span class="hl-attribute">advice-ref</span>=<span class="hl-value">"txAdvice"</span> <span class="hl-attribute">pointcut-ref</span>=<span class="hl-value">"productServiceMethods"</span>/&gt;
  &lt;<span class="hl-tag">/aop:config</span>&gt;

  &lt;<span class="hl-tag">tx:advice</span> <span class="hl-attribute">id</span>=<span class="hl-value">"txAdvice"</span> <span class="hl-attribute">transaction-manager</span>=<span class="hl-value">"myTxManager"</span>&gt;
    &lt;<span class="hl-tag">tx:attributes</span>&gt;
      &lt;<span class="hl-tag">tx:method</span> <span class="hl-attribute">name</span>=<span class="hl-value">"increasePrice*"</span> <span class="hl-attribute">propagation</span>=<span class="hl-value">"REQUIRED"</span>/&gt;
      &lt;<span class="hl-tag">tx:method</span> <span class="hl-attribute">name</span>=<span class="hl-value">"someOtherBusinessMethod"</span> <span class="hl-attribute">propagation</span>=<span class="hl-value">"REQUIRES_NEW"</span>/&gt;
      &lt;<span class="hl-tag">tx:method</span> <span class="hl-attribute">name</span>=<span class="hl-value">"*"</span> <span class="hl-attribute">propagation</span>=<span class="hl-value">"SUPPORTS"</span> <span class="hl-attribute">read-only</span>=<span class="hl-value">"true"</span>/&gt;
    &lt;<span class="hl-tag">/tx:attributes</span>&gt;
  &lt;<span class="hl-tag">/tx:advice</span>&gt;

&lt;<span class="hl-tag">/beans</span>&gt;</pre><p>Spring JPA allows a configured
      <code class="classname">JpaTransactionManager</code> to expose a JPA transaction
      to JDBC access code that accesses the same JDBC
      <code class="interfacename">DataSource</code>, provided that the registered
      <code class="interfacename">JpaDialect</code> supports retrieval of the
      underlying JDBC <code class="interfacename">Connection</code>. Out of the
      box, Spring provides dialects for the Toplink, Hibernate and OpenJPA JPA
      implementations. See the next section for details on the
      <code class="interfacename">JpaDialect</code> mechanism.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="orm-jpa-dialect"></a>13.5.4&nbsp;<code class="interfacename">JpaDialect</code></h3></div></div></div><p>As an advanced feature <code class="classname">JpaTemplate</code>,
      <code class="classname">JpaTransactionManager</code> and subclasses of
      <code class="classname">AbstractEntityManagerFactoryBean</code> support a custom
      <code class="interfacename">JpaDialect</code>, to be passed into the
      <span class="property">jpaDialect</span> bean property. In such a scenario, the
      DAOs do not receive an
      <code class="interfacename">EntityManagerFactory</code> reference but rather
      a full <code class="classname">JpaTemplate</code> instance (for example,
      passed
      into the <span class="property">jpaTemplate</span> property<code class="classname"> of
      JpaDaoSupport</code>). A <code class="interfacename">JpaDialect</code>
      implementation can enable some advanced features supported by Spring,
      usually in a vendor-specific manner:</p><div class="itemizedlist"><ul type="disc"><li><p>Applying specific transaction semantics such as custom
          isolation level or transaction timeout)</p></li><li><p>Retrieving the transactional JDBC
          <code class="interfacename">Connection</code> for exposure to JDBC-based
          DAOs)</p></li><li><p>Advanced translation of
          <code class="literal">PersistenceExceptions</code> to Spring
          <code class="literal">DataAccessExceptions</code></p></li></ul></div><p>This is particularly valuable for special transaction semantics
      and for advanced translation of exception. The default implementation
      used (<code class="classname">DefaultJpaDialect</code>) does not provide any
      special capabilities and if the above features are required, you have to
      specify the appropriate dialect.</p><p>See the <code class="interfacename">JpaDialect</code> Javadoc for more
      details of its operations and how they are used within Spring's JPA
      support.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="orm-ibatis"></a>13.6&nbsp;iBATIS SQL Maps</h2></div></div></div><p>The iBATIS support in the Spring Framework much resembles the JDBC
    support in that it supports the same template style programming, and as
    with JDBC and other ORM technologies, the iBATIS support works with
    Spring's exception hierarchy and lets you enjoy Spring's IoC
    features.</p><p>Transaction management can be handled through Spring's standard
    facilities. No special transaction strategies are necessary for iBATIS,
    because no special transactional resource involved other than a JDBC
    <code class="interfacename">Connection</code>. Hence, Spring's standard JDBC
    <code class="classname">DataSourceTransactionManager</code> or
    <code class="classname">JtaTransactionManager</code> are perfectly
    sufficient.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.gif"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Spring supports iBATIS 2.x. The iBATIS 1.x support classes are no
      longer provided.</p></td></tr></table></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="orm-ibatis-setup"></a>13.6.1&nbsp;Setting up the <code class="classname">SqlMapClient</code></h3></div></div></div><p>Using iBATIS SQL Maps involves creating SqlMap configuration files
      containing statements and result maps. Spring takes care of loading
      those using the <code class="classname">SqlMapClientFactoryBean</code>. For the
      examples we will be using the following <code class="classname">Account</code>
      class:</p><pre class="programlisting">public class Account {

    private String name;
    private String email; 

    public String getName() {
        return this.name;
    }
 
    public void setName(String name) {
        this.name = name;
    }

    public String getEmail() {
        return this.email;
    }

    public void setEmail(String email) {
        this.email = email;
    }
}</pre><p>To map this <code class="classname">Account</code> class with iBATIS 2.x we
      need to create the following SQL map
      <code class="filename">Account.xml</code>:</p><pre class="programlisting">&lt;<span class="hl-tag">sqlMap</span> <span class="hl-attribute">namespace</span>=<span class="hl-value">"Account"</span>&gt;

  &lt;<span class="hl-tag">resultMap</span> <span class="hl-attribute">id</span>=<span class="hl-value">"result"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"examples.Account"</span>&gt;
    &lt;<span class="hl-tag">result</span> <span class="hl-attribute">property</span>=<span class="hl-value">"name"</span> <span class="hl-attribute">column</span>=<span class="hl-value">"NAME"</span> <span class="hl-attribute">columnIndex</span>=<span class="hl-value">"1"</span>/&gt;
    &lt;<span class="hl-tag">result</span> <span class="hl-attribute">property</span>=<span class="hl-value">"email"</span> <span class="hl-attribute">column</span>=<span class="hl-value">"EMAIL"</span> <span class="hl-attribute">columnIndex</span>=<span class="hl-value">"2"</span>/&gt;
  &lt;<span class="hl-tag">/resultMap</span>&gt;

  &lt;<span class="hl-tag">select</span> <span class="hl-attribute">id</span>=<span class="hl-value">"getAccountByEmail"</span> <span class="hl-attribute">resultMap</span>=<span class="hl-value">"result"</span>&gt;
    select ACCOUNT.NAME, ACCOUNT.EMAIL
    from ACCOUNT
    where ACCOUNT.EMAIL = #value#
  &lt;<span class="hl-tag">/select</span>&gt;

  &lt;<span class="hl-tag">insert</span> <span class="hl-attribute">id</span>=<span class="hl-value">"insertAccount"</span>&gt;
    insert into ACCOUNT (NAME, EMAIL) values (#name#, #email#)
  &lt;<span class="hl-tag">/insert</span>&gt;

&lt;<span class="hl-tag">/sqlMap</span>&gt;</pre><p>The configuration file for iBATIS 2 looks like this:</p><pre class="programlisting">&lt;<span class="hl-tag">sqlMapConfig</span>&gt;

  &lt;<span class="hl-tag">sqlMap</span> <span class="hl-attribute">resource</span>=<span class="hl-value">"example/Account.xml"</span>/&gt;

&lt;<span class="hl-tag">/sqlMapConfig</span>&gt;</pre><p>Remember that iBATIS loads resources from the class path, so be
      sure to add the<code class="filename">Account.xml</code> file to the class
      path.</p><p>We can use the <code class="classname">SqlMapClientFactoryBean</code> in
      the Spring container. Note that with iBATIS SQL Maps 2.x, the JDBC
      <code class="interfacename">DataSource</code> is usually specified on the
      <code class="classname">SqlMapClientFactoryBean</code>, which enables lazy
      loading. This is the configuration needed for these bean
      definitions:</p><pre class="programlisting">&lt;<span class="hl-tag">beans</span>&gt;

  &lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"dataSource"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"org.apache.commons.dbcp.BasicDataSource"</span> <span class="hl-attribute">destroy-method</span>=<span class="hl-value">"close"</span>&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"driverClassName"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"${jdbc.driverClassName}"</span>/&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"url"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"${jdbc.url}"</span>/&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"username"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"${jdbc.username}"</span>/&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"password"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"${jdbc.password}"</span>/&gt;
  &lt;<span class="hl-tag">/bean</span>&gt;

  &lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"sqlMapClient"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"org.springframework.orm.ibatis.SqlMapClientFactoryBean"</span>&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"configLocation"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"WEB-INF/sqlmap-config.xml"</span>/&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"dataSource"</span> <span class="hl-attribute">ref</span>=<span class="hl-value">"dataSource"</span>/&gt;
  &lt;<span class="hl-tag">/bean</span>&gt;

&lt;<span class="hl-tag">/beans</span>&gt;</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="orm-ibatis-template"></a>13.6.2&nbsp;Using <code class="classname">SqlMapClientTemplate</code> and
      <code class="classname">SqlMapClientDaoSupport</code></h3></div></div></div><p>The <code class="classname">SqlMapClientDaoSupport</code> class offers a
      supporting class similar to the <code class="classname">SqlMapDaoSupport</code>.
      We extend it to implement our DAO:</p><pre class="programlisting"><span class="hl-keyword">public</span> <span class="hl-keyword">class</span> SqlMapAccountDao <span class="hl-keyword">extends</span> SqlMapClientDaoSupport <span class="hl-keyword">implements</span> AccountDao {

    <span class="hl-keyword">public</span> Account getAccount(String email) <span class="hl-keyword">throws</span> DataAccessException {
        <span class="hl-keyword">return</span> (Account) getSqlMapClientTemplate().queryForObject(<span class="hl-string">"getAccountByEmail"</span>, email);
    }

    <span class="hl-keyword">public</span> <span class="hl-keyword">void</span> insertAccount(Account account) <span class="hl-keyword">throws</span> DataAccessException {
        getSqlMapClientTemplate().update(<span class="hl-string">"insertAccount"</span>, account);
    }
}</pre><p>In the DAO, we use the pre-configured
      <code class="classname">SqlMapClientTemplate</code> to execute the queries,
      after setting up the <code class="literal">SqlMapAccountDao</code> in the
      application context and wiring it with our
      <code class="literal">SqlMapClient</code> instance:</p><pre class="programlisting">&lt;<span class="hl-tag">beans</span>&gt;

  &lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"accountDao"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"example.SqlMapAccountDao"</span>&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"sqlMapClient"</span> <span class="hl-attribute">ref</span>=<span class="hl-value">"sqlMapClient"</span>/&gt;
  &lt;<span class="hl-tag">/bean</span>&gt;

&lt;<span class="hl-tag">/beans</span>&gt;</pre><p>An <code class="classname">SqlMapTemplate</code> instance can also be
      created manually, passing in the <code class="literal">SqlMapClient</code> as
      constructor argument. The <code class="literal">SqlMapClientDaoSupport</code> base
      class simply preinitializes a
      <code class="classname">SqlMapClientTemplate</code> instance for us.</p><p>The <code class="classname">SqlMapClientTemplate</code> offers a generic
      <code class="literal">execute</code> method, taking a custom
      <code class="literal">SqlMapClientCallback</code> implementation as argument. This
      can, for example, be used for batching:</p><pre class="programlisting"><span class="hl-keyword">public</span> <span class="hl-keyword">class</span> SqlMapAccountDao <span class="hl-keyword">extends</span> SqlMapClientDaoSupport <span class="hl-keyword">implements</span> AccountDao {

    <span class="hl-keyword">public</span> <span class="hl-keyword">void</span> insertAccount(Account account) <span class="hl-keyword">throws</span> DataAccessException {
        getSqlMapClientTemplate().execute(<span class="hl-keyword">new</span> SqlMapClientCallback() {
            <span class="hl-keyword">public</span> Object doInSqlMapClient(SqlMapExecutor executor) <span class="hl-keyword">throws</span> SQLException {
                executor.startBatch();
                executor.update(<span class="hl-string">"insertAccount"</span>, account);
                executor.update(<span class="hl-string">"insertAddress"</span>, account.getAddress());
                executor.executeBatch();
            }
        });
    }
}</pre><p>In general, any combination of operations offered by the native
      <code class="literal">SqlMapExecutor</code> API can be used in such a callback.
      Any thrown <code class="literal">SQLException</code> is converted automatically to
      Spring's generic <code class="classname">DataAccessException</code>
      hierarchy.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="orm-ibatis-straight"></a>13.6.3&nbsp;Implementing DAOs based on plain iBATIS API</h3></div></div></div><p>DAOs can also be written against plain iBATIS API, without any
      Spring dependencies, directly using an injected
      <code class="literal">SqlMapClient</code>. The following example shows a
      corresponding DAO implementation:</p><pre class="programlisting"><span class="hl-keyword">public</span> <span class="hl-keyword">class</span> SqlMapAccountDao <span class="hl-keyword">implements</span> AccountDao {
        
    <span class="hl-keyword">private</span> SqlMapClient sqlMapClient;
    
    <span class="hl-keyword">public</span> <span class="hl-keyword">void</span> setSqlMapClient(SqlMapClient sqlMapClient) {
        <span class="hl-keyword">this</span>.sqlMapClient = sqlMapClient;
    }

    <span class="hl-keyword">public</span> Account getAccount(String email) {
        <span class="hl-keyword">try</span> {
            <span class="hl-keyword">return</span> (Account) <span class="hl-keyword">this</span>.sqlMapClient.queryForObject(<span class="hl-string">"getAccountByEmail"</span>, email);
        }
        <span class="hl-keyword">catch</span> (SQLException ex) {
            <span class="hl-keyword">throw</span> <span class="hl-keyword">new</span> MyDaoException(ex);
        }
    }

    <span class="hl-keyword">public</span> <span class="hl-keyword">void</span> insertAccount(Account account) <span class="hl-keyword">throws</span> DataAccessException {
        <span class="hl-keyword">try</span> {
            <span class="hl-keyword">this</span>.sqlMapClient.update(<span class="hl-string">"insertAccount"</span>, account);
        }
        <span class="hl-keyword">catch</span> (SQLException ex) {
            <span class="hl-keyword">throw</span> <span class="hl-keyword">new</span> MyDaoException(ex);
        }
    }
}</pre><p>In this scenario, you need to handle the
      <code class="literal">SQLException</code> thrown by the iBATIS API in a custom
      fashion, usually by wrapping it in your own application-specific DAO
      exception. Wiring in the application context would still look like it
      does in the example for the
      <code class="classname">SqlMapClientDaoSupport</code>,
      due to the fact that the plain iBATIS-based DAO still follows the
      dependency injection pattern:</p><pre class="programlisting">&lt;<span class="hl-tag">beans</span>&gt;

  &lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"accountDao"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"example.SqlMapAccountDao"</span>&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"sqlMapClient"</span> <span class="hl-attribute">ref</span>=<span class="hl-value">"sqlMapClient"</span>/&gt;
  &lt;<span class="hl-tag">/bean</span>&gt;

&lt;<span class="hl-tag">/beans</span>&gt;</pre></div></div></div><!--Begin LoopFuse code--><script src="http://loopfuse.net/webrecorder/js/listen.js" type="text/javascript"></script><script type="text/javascript">
			_lf_cid = "LF_48be82fa";
			_lf_remora();
		</script><!--End LoopFuse code--><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="jdbc.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="spring-data-tier.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="oxm.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">12.&nbsp;Data access with JDBC&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;14.&nbsp;Marshalling XML using O/X Mappers</td></tr></table></div><!-- Begin 2nd Google code - a mod -->
<script type="text/javascript">
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));</script>
<script type="text/javascript">
var OrgTracker = _gat._getTracker("UA-2728886-2"); OrgTracker._setDomainName("none");
OrgTracker._setAllowLinker(true);
OrgTracker._trackPageview();
</script>
 <!-- End 2nd Google code -->


<script type="text/javascript">

function detectLastFrame() {
   var thisF = this.window;
   var allF = parent.top.frames;
   return allF[allF.length - 1] == thisF; }

// Only inject the following code if this is a normal page or the last // frame of a frameset.
if (parent.top.frames.length == 0 || detectLastFrame()) {
    // Inject the SpringSource search widget too.
    document.write(unescape("%3Cscript src='http://search.springsource.org/widget/searchtool.js' type='text/javascript'%3E%3C/script%3E"));
    // Inject the Eloqua code
    document.write(unescape("%3Cscript src='/elqNow/elqCfg.js' type='text/javascript'%3E%3C/script%3E"));
    document.write(unescape("%3Cscript src='/elqNow/elqImg.js' type='text/javascript'%3E%3C/script%3E"));

}
</script>
</body>
</html>